uv

Cómo funciona

uv resuelve dependencias, mantiene uv.lock y sincroniza el entorno virtual con el proyecto. También administra versiones de Python y permite ejecutar utilidades aisladas.

Ejemplo: crear y reproducir un proyecto

uv init ejemplo
cd ejemplo
uv add pydantic
uv run python -c "import pydantic; print(pydantic.__version__)"

# En CI, con pyproject.toml y uv.lock versionados
uv sync --locked

Qué sustituye

Antes	Con uv
pyenv install 3.12	uv python install 3.12
python -m venv .venv + pip install	uv sync
pip-tools / poetry lock	uv lock
pipx install ruff	uv tool install ruff / uvx ruff
pip install -r requirements.txt	uv pip install -r requirements.txt (compatible)

Escrito en Rust por Astral (autores de Ruff), resuelve e instala entre 10 y 100 veces más rápido que pip en escenarios habituales gracias a la caché global y la resolución en paralelo.

Dependencias por grupos

uv add fastapi 'sqlalchemy>=2'
uv add --dev pytest ruff mypy
uv add --group docs mkdocs-material
uv lock --upgrade-package fastapi      # actualizar solo un paquete
uv tree                                 # árbol de dependencias
uv export --format requirements-txt > requirements.txt   # para herramientas que lo necesiten

Scripts autocontenidos (PEP 723)

# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx", "rich"]
# ///
import httpx
from rich import print
print(httpx.get("https://api.github.com").status_code)

uv run script.py crea un entorno temporal con esas dependencias: ideal para utilidades operativas sin un proyecto completo.

Imagen Docker reproducible

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:<versión> /uv /uvx /bin/
WORKDIR /app
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-dev --no-install-project
COPY . .
RUN uv sync --locked --no-dev
CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0"]

Instalar primero solo las dependencias aprovecha la caché de capas: cambiar el código no reinstala paquetes.

Workspaces

Para monorepos Python, [tool.uv.workspace] en el pyproject.toml raíz agrupa varios paquetes con un único lockfile, similar a los workspaces de pnpm. Para CLIs con Typer o modelos con Pydantic, uv simplifica distribuir herramientas internas con uv tool install.

Criterios de implementación

Fija la versión de Python y versiona el lockfile. --locked evita actualizar silenciosamente una resolución que ya no coincide con el proyecto. Aun con dependencias fijadas, revisa disponibilidad de paquetes y bibliotecas nativas por plataforma.