uv - La Cadena de Herramientas Rápida

uv es un gestor de paquetes de Python todo en uno escrito en Rust. Reemplaza pip, venv, pip-tools y pyenv con una única CLI rápida, siendo el predeterminado recomendado para proyectos Python 3.14.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

# Instalar uv
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Nuevo proyecto
uv init myapp && cd myapp
uv add fastapi pydantic
uv run uvicorn myapp.main:app --reload
 
# Proyecto existente
uv sync
uv run pytest

Cuándo usar esto:

• Al iniciar un nuevo proyecto Python 3.14
• Para reemplazar flujos de trabajo lentos de pip install + venv manual
• Pipelines de CI que necesitan instalaciones de dependencias en menos de un segundo
• Para gestionar múltiples versiones de Python sin pyenv

Ejemplo de Trabajo

#!/usr/bin/env bash
set -euo pipefail
 
# Inicializar un servicio FastAPI con uv
uv init invoice-api
cd invoice-api
 
uv add "fastapi>=0.115" "uvicorn[standard]>=0.34" "pydantic>=2"
 
cat > src/invoice_api/main.py <<'PY'
from fastapi import FastAPI
from pydantic import BaseModel
 
app = FastAPI()
 
class Invoice(BaseModel):
    id: int
    amount: float
 
@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}
 
@app.post("/invoices")
def create(invoice: Invoice) -> Invoice:
    return invoice
PY
 
uv run uvicorn invoice_api.main:app --host 0.0.0.0 --port 8000

Lo que esto demuestra:

• uv init crea la estructura de pyproject.toml, src/ y .venv
• uv add resuelve dependencias y actualiza uv.lock
• uv run ejecuta dentro del entorno del proyecto sin activación manual
• Los puntos de entrada se resuelven automáticamente desde el paquete src/

Inmersión Profunda

Cómo Funciona

• uv utiliza una caché global de paquetes y enlaces duros en directorios .venv por proyecto.
• La resolución se realiza en Rust, típicamente 10-100 veces más rápido que pip para árboles de dependencias grandes.
• uv.lock es un archivo de bloqueo universal (compatible con PEP 751) con versiones exactas y hashes.
• uv python gestiona las descargas de intérpretes junto con la gestión de paquetes.

Comandos Principales

Notas de Python

# Fijar intérprete para el proyecto
uv python pin 3.14
 
# Ejecutar contra una versión específica sin cambiar el pin
uv run --python 3.13 pytest
 
# Actualizar todas las dependencias
uv lock --upgrade

Errores Comunes

• Olvidar uv sync después de clonar - Las importaciones fallan con ModuleNotFoundError. Solución: ejecutar uv sync (o uv sync --frozen en CI) antes de cualquier comando.
• Mezclar pip y uv en el mismo venv - Los conflictos de metadatos causan desajustes sutiles de versiones. Solución: elegir una herramienta por proyecto; usar uv pip si necesitas semántica de pip.
• No confirmar uv.lock - Los compañeros de equipo obtienen versiones de dependencias diferentes. Solución: confirmar el archivo de bloqueo; usar uv sync --frozen en CI.
• Ejecutar uv add sin actualizar el bloqueo - pyproject.toml y el archivo de bloqueo divergen. Solución: uv add actualiza ambos; si editas pyproject.toml manualmente, ejecuta uv lock después.
• uv pip install global - Contamina el intérprete del sistema. Solución: trabajar siempre dentro de un proyecto (uv init / uv sync) o pasar --python explícitamente.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Entornos y Empaquetado - Fundamentos de venv y aislamiento
• pyproject.toml Explicado - Estructura de metadatos del proyecto
• Resolución de Dependencias y Archivos de Bloqueo - Estrategias de fijación
• Gestión de Versiones de Python - Pruebas multi-versión

Versiones de la Pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.