Cómo configurar un proyecto de Python rápido y reproducible con uv

Cuando apuntas un agente de codificación con IA como Claude Code o Codex a un proyecto de Python, la mitad de la fricción no tiene nada que ver con el modelo. Viene del entorno: paquetes que faltan, la versión de Python equivocada, un virtualenv que el agente olvidó activar, o un compañero de equipo al que "le funciona en su máquina". La solución es un proyecto que sea reproducible por defecto, y la forma más rápida de conseguir uno hoy es uv, la cadena de herramientas de Python basada en Rust de Astral.

uv reemplaza a pip, venv, pip-tools y pyenv con un único comando rápido, y escribe un lockfile para que el mismísimo árbol de dependencias se instale igual en todas partes. Esta guía te lleva de cero a un proyecto bloqueado y ejecutable en pocos minutos.

Por qué el entorno le importa a un agente

Un agente de IA ejecuta comandos en tu shell y lee los errores que regresan. Si tu proyecto no tiene dependencias declaradas ni una versión de Python fijada, el agente tiene que adivinar — y una mala suposición lo manda por la madriguera de instalar paquetes globalmente o de editar el intérprete equivocado. Un proyecto con un pyproject.toml y un uv.lock le da al agente una única fuente de verdad: puede ejecutar uv sync, obtener los paquetes correctos y seguir adelante. Tú dedicas tu tiempo de revisión a la lógica, no a la arqueología del entorno.

Instala uv

En macOS o Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

En Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv es un único binario autocontenido, así que no hay nada más que configurar.

Inicia un proyecto con un solo comando

uv init weather-cli
cd weather-cli

Eso genera un proyecto funcional: un pyproject.toml para los metadatos y las dependencias, un archivo .python-version, un main.py inicial, un README.md y un .gitignore. No creas ni activas un virtualenv a mano — uv gestiona un .venv por ti en el momento en que lo necesitas.

Añade dependencias (y por qué importa el lockfile)

uv add requests

Esto hace tres cosas a la vez: registra requests en pyproject.toml, resuelve el árbol completo de dependencias y escribe uv.lock con versiones exactas y fijadas para todas las plataformas. También puedes fijar la versión al añadirla:

uv add 'requests==2.31.0'

Confirma uv.lock en Git. Es la diferencia entre "instala el último requests" (que se va desviando con el tiempo) e "instala el árbol exacto que probamos". Cuando tu agente — o tu CI, o un nuevo compañero de equipo — ejecuta uv sync, obtiene un entorno idéntico byte a byte.

Ejecuta código sin activar nada

uv run main.py

uv run se asegura de que el entorno esté sincronizado y luego ejecuta dentro de él — sin el baile de source .venv/bin/activate. Esto importa especialmente para los agentes: cada llamada a una herramienta suele ser un shell nuevo, así que "activa y luego ejecuta" se rompe con frecuencia, mientras que un único uv run siempre funciona. Puedes envolver cualquier comando:

uv run -- pytest -q
uv run -- flask run -p 3000

Fija una versión de Python para que el agente y el CI coincidan

uv python pin 3.12

Esto escribe la versión en .python-version, y uv descargará y usará ese intérprete automáticamente — sin necesidad de un Python del sistema. Ahora la versión con la que desarrollas es la versión que usan tu agente, tus compañeros de equipo y tu CI por igual.

Un breve ejemplo práctico

Supón que le pides a un agente que "añada un comando que obtenga el clima de hoy". Con uv instalado, todo el ciclo queda limpio:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# el agente edita main.py para llamar a una API...
uv run main.py

El agente nunca tiene que razonar sobre qué intérprete está activo ni si requests está instalado — esos hechos están declarados en archivos que puede leer. Si introduce una nueva dependencia, ejecuta uv add y el lockfile se actualiza. Si algo se rompe en el CI, uv sync reproduce el entorno exacto localmente para que puedas depurarlo.

Hacia dónde va uv

uv y sus herramientas hermanas ruff (linter/formateador) y ty (verificador de tipos) tienen una amplia adopción — solo uv supera con creces los 100 millones de descargas al mes. En marzo de 2026, OpenAI acordó adquirir Astral, la empresa detrás de ellas, para incorporar la cadena de herramientas a su plataforma Codex, comprometiéndose a mantener de código abierto las herramientas con licencia MIT (OpenAI, Simon Willison). Por ahora, la conclusión práctica no cambia: uv es el camino más rápido hacia un proyecto de Python sobre el que tu agente de IA puede construir sin adivinar.

Referencia rápida

Tarea	Comando
Crear un proyecto	uv init <name>
Añadir una dependencia	uv add <package>
Fijar Python	uv python pin 3.12
Ejecutar código	uv run <file or command>
Reproducir el entorno	uv sync
Actualizar el lockfile	uv lock --upgrade-package <pkg>