Python uv: Una Forma Más Rápida de Administrar Proyectos y Dependencias

Los proyectos de Python suelen comenzar con una secuencia conocida: crear un entorno virtual, actualizar pip, instalar paquetes y guardar las dependencias en un archivo requirements.txt. Ese flujo de trabajo funciona, pero encadena varias herramientas y comandos separados, y es fácil que un principiante pierda el hilo de qué hace cada paso.

Python uv es un administrador de paquetes y proyectos rápido y moderno creado por Astral, y está diseñado para reemplazar la mayor parte de ese flujo de trabajo con una sola herramienta consistente. uv puede encargarse de todo lo que normalmente cubren pip, venv y herramientas como pipx, además de generar un archivo de bloqueo (lockfile) que registra las versiones exactas de las dependencias usadas en un proyecto, algo que el antiguo flujo con requirements.txt nunca garantizaba por sí solo.

Si eres un diseñador web principiante que se está expandiendo hacia Python (para scripts de automatización, una pequeña aplicación con Flask o trabajo con datos junto con proyectos de clientes), vale la pena aprender uv desde el principio. Elimina buena parte de la fricción de configuración que hace que la administración de proyectos de Python parezca más complicada de lo necesario, sobre todo si vienes del diseño web y no de la ingeniería de software tradicional.

Esta guía cubre por qué vale la pena usar uv, cómo instalarlo, cómo crear y administrar un proyecto con él y una hoja de referencia completa de comandos que puedes consultar mientras avanzas.

¿Por Qué Usar uv?

Python uv es útil siempre que quieras un flujo de trabajo de Python más simple, rápido y reproducible.

• Crea y administra entornos virtuales para los proyectos.
• Instala paquetes rápidamente usando una caché global.
• Administra las dependencias del proyecto en pyproject.toml.
• Genera uv.lock para que las instalaciones puedan reproducirse exactamente.
• Puede ejecutar comandos en el entorno de un proyecto sin activarlo manualmente.
• Puede instalar y ejecutar herramientas independientes de Python.

uv no elimina la necesidad de entender los entornos de Python; reúne las operaciones comunes de entornos y dependencias detrás de una sola interfaz de línea de comandos consistente, en lugar de varias herramientas distintas.

Por Qué Esto Importa para los Diseñadores Web

No necesitas formación en ciencias de la computación para beneficiarte de uv. Si estás aprendiendo Python para automatizar una tarea repetitiva, construir una pequeña herramienta interna o analizar datos de clientes, uv significa menos comandos que memorizar y menos formas de que la configuración de un proyecto se rompa en silencio, lo que te permite dedicar más tiempo al proyecto real y menos a pelear con tus herramientas.

Instalar uv

En Windows, instala uv con PowerShell:

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

En macOS o Linux, usa el instalador de shell:

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

También puedes instalar uv con un administrador de paquetes. Por ejemplo, los usuarios de Homebrew pueden ejecutar:

brew install uv

Confirma que la instalación funciona:

uv --version

Reinicia tu terminal si el comando uv no se encuentra inmediatamente después de la instalación.

Crear un Proyecto de Python

Crea un proyecto nuevo con uv init:

mkdir weather-app
cd weather-app
uv init

Esto crea una estructura de proyecto básica, que incluye un archivo pyproject.toml y un punto de entrada de Python. Los archivos exactos pueden variar según las opciones que indiques, pero pyproject.toml es el archivo de configuración central del proyecto.

Puedes especificar directamente el nombre del proyecto:

uv init --name weather-app

Para empezar con una versión particular de Python, usa la opción --python:

uv init --python 3.12

Si esa versión de Python no está instalada localmente, uv puede descargar una copia administrada cuando sea necesario.

Agregar y Quitar Dependencias

Agrega un paquete con uv add:

uv add requests

Esto actualiza pyproject.toml, resuelve versiones compatibles y actualiza uv.lock. Agrega varios paquetes a la vez cuando pertenezcan a la misma funcionalidad:

uv add pandas matplotlib

Las dependencias solo para desarrollo pueden colocarse en un grupo de dependencias de desarrollo:

uv add --dev pytest ruff

Quita un paquete con:

uv remove requests

Para instalar un rango de versiones específico, inclúyelo en el requisito:

uv add "django>=5.0,<6"

Ejecutar Tu Proyecto

Usa uv run para ejecutar un comando en el entorno del proyecto:

uv run main.py

Para un paquete configurado con un script de proyecto, ejecuta el nombre de su script. Por ejemplo, si pyproject.toml contiene un script llamado start, usa:

uv run start

También puedes ejecutar herramientas de desarrollo sin activar manualmente el entorno virtual:

uv run pytest
uv run ruff check .

Esta es una de las partes más cómodas del flujo de trabajo. El comando deja claro qué entorno de proyecto debe proporcionar la herramienta y sus dependencias.

Entender uv.lock y uv sync

El archivo uv.lock registra las versiones resueltas de las dependencias directas y transitivas del proyecto. Inclúyelo en el control de versiones para que otros desarrolladores y los sistemas de despliegue puedan reproducir el mismo entorno.

Para sincronizar el entorno con los archivos del proyecto y el archivo de bloqueo, ejecuta:

uv sync

Para una instalación reproducible en integración continua, usa las dependencias bloqueadas sin modificar el archivo de bloqueo:

uv sync --locked

Cuando pyproject.toml cambie, ejecuta uv lock o uv sync para resolver el nuevo conjunto de dependencias y revisa los cambios resultantes en el archivo de bloqueo.

Usar un Entorno Virtual Directamente

La mayoría de los flujos de trabajo de proyectos no requieren activación manual, pero uv puede crear un entorno virtual de forma explícita:

uv venv

El entorno predeterminado se crea en un directorio .venv. Actívalo con el comando correspondiente a tu sistema operativo si quieres trabajar con los comandos ordinarios python y pip.

Windows PowerShell:

.venv\Scripts\Activate.ps1

macOS y Linux:

source .venv/bin/activate

Para un proyecto administrado con pyproject.toml, prefiere uv add, uv remove, uv sync y uv run para que la configuración y el archivo de bloqueo se mantengan actualizados.

Instalar Herramientas Independientes de Python

uv puede instalar herramientas de línea de comandos en entornos aislados. Por ejemplo:

uv tool install ruff

También puedes ejecutar una herramienta sin instalarla de forma permanente:

uvx ruff check .

Esto es útil para herramientas ocasionales o para probar un comando antes de agregarlo a un proyecto.

Un Flujo de Trabajo Diario Práctico

Un proyecto pequeño podría usar esta secuencia:

uv init --python 3.12
uv add requests
uv add --dev pytest ruff
uv run pytest
uv run ruff check .
uv sync --locked

Incluye en el control de versiones tanto pyproject.toml como uv.lock. No incluyas .venv, porque es un entorno local generado y puede recrearse con uv sync.

Migrar desde requirements.txt

Si un proyecto existente ya tiene un archivo requirements.txt, crea o entra al directorio del proyecto y agrega los requisitos listados:

uv init
uv add -r requirements.txt

Revisa los archivos pyproject.toml y uv.lock resultantes antes de eliminar el archivo de requisitos antiguo. Si el despliegue u otra herramienta todavía espera un requirements.txt, sigue generando o manteniendo ese archivo hasta que el resto del proyecto haya pasado al nuevo flujo de trabajo.

Hoja de Referencia de Comandos Comunes

Conclusión

Python uv reúne la inicialización de proyectos, la administración de versiones de Python, los entornos virtuales, las dependencias, los archivos de bloqueo y la ejecución de comandos en un solo flujo de trabajo consistente. Es una excelente opción para proyectos nuevos de Python y una forma práctica de simplificar proyectos existentes que hoy dependen de varios comandos separados de pip y venv encadenados.

Para un diseñador web principiante que se inicia en Python, vale la pena aprender uv desde tu primer proyecto en lugar de adaptarlo después: cuantas menos piezas móviles tengas que administrar manualmente, más de tu atención se queda en el proyecto real y no en las herramientas que lo rodean.

El hábito más importante que debes llevarte de esta guía: trata pyproject.toml como la declaración de dependencias de tu proyecto y uv.lock como su registro de reproducibilidad. Incluye ambos archivos en el control de versiones, y podrás recrear un entorno nuevo en cualquier máquina con un solo comando uv sync: sin configuración manual, sin adivinanzas y sin sorpresas de “en mi máquina sí funciona”.