Gestionar las dependencias Python con uv

uv gestiona las dependencias y el entorno virtual de un proyecto Python. Todo se basa en tres archivos, siempre en el mismo orden:

pyproject.toml ──uv lock──▶ uv.lock ──uv sync──▶ .venv/
lo que se quiere           versiones exactas    lo que está instalado
(rangos >=, <)

Archivo	Papel	En git
pyproject.toml	Dependencias deseadas, con rangos de versiones	Sí
uv.lock	Versiones exactas resueltas, para todas las plataformas	Sí
.venv/	Entorno instalado en la máquina	No

Regla que recordar

Se hace siempre commit de pyproject.toml y uv.lock juntos.

En el equipo de desarrollo

Etapa	Comando
Añadir una dependencia	uv add httpx
Añadir una dependencia de desarrollo	uv add --dev pytest
Quitar una dependencia	uv remove httpx
Después de un git pull	uv sync
pyproject.toml editado a mano	uv lock y después uv sync
Actualizar un paquete	uv lock --upgrade-package httpx
Actualizarlo todo	uv lock --upgrade
Ejecutar un comando	uv run pytest
Antes del commit	uv lock --check

uv add y uv remove actualizan las tres capas a la vez. uv run sincroniza el .venv antes de ejecutar el comando.

Si el proyecto declara sus herramientas de desarrollo como dependencias opcionales ([project.optional-dependencies]) en lugar de un grupo de desarrollo, se usa uv add --optional dev pytest y uv sync --extra dev.

En integración continua

bash

uv sync --locked
uv run pytest

En el servidor

bash

uv cache prune --ci
uv sync --locked --no-dev

uv cache prune --ci vacía la caché de paquetes descargados. Sin él, la caché conserva cada versión instalada y acaba llenando el disco.

--locked o --frozen

• --locked instala en el .venv los paquetes en las versiones exactas listadas en uv.lock, y falla si ya no corresponde a pyproject.toml. Es la opción para CI y producción: se detecta un pyproject.toml subido sin su lock.
• --frozen también instala las versiones de uv.lock, pero sin comprobar que sigue correspondiendo a pyproject.toml. Mejor evitarlo, salvo casos particulares.