Cómo gestionar un proyecto Python con uv?

Esta herramienta ofrece una alternativa rápida y completa a otras como pip, pip-tools o poetry.

Con uv puedes instalar diferentes versiones de Python, crear proyectos desde cero, gestionar entornos virtuales, añadir y remover dependencias garantizando reproducibilidad, e incluso construir y publicar tus proyectos en PyPI. Todo desde un único flujo de trabajo.

En esta guía aprenderás lo básico de cómo usar uv para ejecutar las tareas más comunes de gestión de proyectos Python, desde la instalación hasta la distribución.

Instalar uv en tu sistema

En macOS y Linux, puedes instalar uv con el commando siguiente:

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

Si no dispones de curl en tu sistema, entonces puedes usar wget:

$ wget -qO- https://astral.sh/uv/install.sh | sh

En Windows, puedes usar el commando:

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

Una vez concluida la instalación, uv estará disponible en tu sistema. Puedes comprobarla con el comando uv --version.

Gestionar múltiples versiones de Python

Con uv puedes instalar y usar distintas versiones de Python fácilmente. Para instalar una versión de Python, por ejemplo la 3.13, usa el comando siguiente:

$ uv python install 3.13

Esto te permite trabajar con varios proyectos que requieran versiones diferentes del lenguaje.

Con el comando uv python list, puedes listar las versiones disponibles y con uv python pin <version>, puedes fijar la versión de Python que quiere emplear en un proyecto específico.

Iniciar un proyecto Python con uv

Con uv puedes crear la estructura inicial de tus nuevos proyectos:

$ uv init project_name

Este comando crea la estructura de proyecto siguiente:

project_name/
│
├── .git/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Aquí tienes un repositorio Git con su correspondiente archivo .gitignore. Luego tienes el archivo .python-version donde uv almacena la versión de Python para el proyecto. El archivo README.md provee el espacio para la documentación básica del proyecto.

Seguidamente tienes el archivo main.py que es el script de entrada del proyecto. Puedes modificarlo según tus necesidades o puedes incluso reemplazarlo por otro. Finalmente, tienes el archivo pyproject.toml que contiene la configuración necesaria para construir y distribuir tu proyecto.

Alternativamente, puedes emplear varias estructuras disponibles en dependencia de tus necesidades:

$ uv init --app app_name
$ uv init --lib library_name
$ uv init --pkg package_name
$ uv init --script script_name

Cada tipo genera una estructura inicial de archivos adaptada al caso. Puedes usar esta estructura como punto de partida para programar tu proyecto.

Debes notar que estos comandos crean el directorio raíz del proyecto usando el nombre suministrado. Si ya has creado el directorio, entonces puedes ejecutar uv init . dentro del mismo.

Una vez que has inicializado un proyecto de aplicación, puedes ejecutarlo con el comando uv run main.py.

Gestionar dependencias de proyectos

Uno de los puntos fuertes de uv es la gestión de dependencias. Con uv puedes instalar y desinstalar dependencias de manera rápida y precisa. Además, uv mantiene un estricto registro y control de dependencias que facilita la reproducibilidad de tu entrono de desarrollo en otros sistemas. Esta característica es fundamental cuando trabajas en equipo.

Cuando añades dependencias con uv, se actualizan automáticamente los archivos pyproject.toml y uv.lock. El primero declara las dependencias, mientras que el segundo mantiene un record estricto de las versiones instaladas.

A continuación aprenderás cómo instalar y desinstalar dependencias externas con uv.

Crear un entorno virtual para tu proyecto

Luego que has inicializado tu proyecto, puedes crear un entorno virtual Python manualmente:

$ uv venv

El nombre del directorio del entorno virtual es .venv por defecto, pero puede usar el nombre que desees con solo añadirlo después del subcomando venv.

El entorno virtual hará referencia al intérprete de Python disponible directamente en tu sistema, entorno de trabajo o shell.

Debes saber que el entorno virtual se crea automáticamente (si es que no existe) cuando ejecutas comandos como uv run, uv add, uv sync, o uv lock.

Instalar dependencias de ejecución

Las dependencias de ejecución son aquellas bibliotecas o paquetes que empleas directamente en el código de tu proyecto.

Por ejemplo, digamos que estás creando un proyecto the Inteligencia Artificial y quieres emplear la API de OpenAI. Puedes instalar la librería openai con el siguiente commando:

$ uv add openai

Este comando añade la librería openai al proyecto como dependencia de ejecución.

Instalar dependencias de desarrollo

Las dependencias de desarrollo son aquellas que necesitas durante el ciclo de desarrollo de tu proyecto. Por ejemplo, puedes necesitar pytest para escribir y ejecutar test unitarios para tu proyecto:

$ uv add --dev pytest

Este comando instala pytest como dependencia de desarrollo, actualizando los archivos uv.lock y pyproject.toml de manera adecuada.

Desinstalar dependencias

Para eliminar un paquete o biblioteca que ya habías instalado y que no necesitas más, puedes usar el comando siguiente:

$ uv remove pytest

Este comando desinstala la biblioteca pytest y todas sus dependencias transitivas, dejando tu entorno virtual de trabajo limpio de paquetes no necesarios. También actualiza el archivo uv.lock de acuerdo con los cambios.

Distribuir y publicar el proyecto

Con uv también puedes empaquetar y publicar tu proyecto:

$ uv build
$ uv publish --token tu_token_aquí

El primer comando genera los artefactos de distribución que se guardan en el directorio dist/ por defecto. El segundo comando sube estos artefactos a PyPI.

Debes notar que para que estos comandos funcionen correctamente, es necesario configurar el script de entrada del proyecto y el sistema de construcción (build system). Todo esto en el archivo pyproject.toml de tu proyecto.

Conclusión

Con uv puedes gestionar todo el ciclo de vida de un proyecto Python desde la línea de comandos de manera rápida, precisa y eficiente. Es una alternativa ligera y moderna frente a herramientas como poetry y puede reemplazar la funcionalidad de herramientas como pyenv, pip, venv, pip-tools, twine entre otras.