Python UV: La Guía Definitiva del Gestor de Paquetes de Python más Rápido

¿Qué es Python UV?

UV es un moderno gestor e instalador de paquetes Python de alto rendimiento escrito en Rust. Sirve como sustituto de las herramientas tradicionales de gestión de paquetes de Python, como pip, y ofrece mejoras significativas en velocidad, fiabilidad y resolución de dependencias.

Esta herramienta representa una nueva generación de gestores de paquetes de Python, diseñados para abordar puntos problemáticos comunes en el ecosistema de Python, como los tiempos de instalación lentos, los conflictos de dependencias y la complejidad de la gestión del entorno. UV lo consigue gracias a su arquitectura innovadora y a su eficiente implementación, que lo hacen entre 10 y 100 veces más rápido que los gestores de paquetes tradicionales.

Características clave que hacen destacar a la UV:

• Rápida instalación de paquetes y resolución de dependencias
• Compatible con las herramientas y flujos de trabajo de Python existentes
• Gestión integrada del entorno virtual
• Apoyo a las normas modernas de envasado
• Bloqueo fiable de dependencias y entornos reproducibles
• Funcionamiento eficiente en memoria, especialmente para grandes proyectos

Tanto si trabajas en pequeños proyectos personales como si gestionas aplicaciones Python a gran escala, UV proporciona una solución sólida y eficaz para la gestión de paquetes. En este tutorial, cubriremos todos los aspectos esenciales de la UV para que puedas empezar a utilizarla inmediatamente.

La diferencia entre UV, Poesía, PIP, Conda y virtualenv

La primera pregunta que suelen hacerse los desarrolladores antes de cambiar a una nueva herramienta es: "¿Cómo se compara con la que ya estoy utilizando?". En el ámbito de la gestión de proyectos y dependencias de Python, estas cuatro herramientas son ya las más comunes:

• PIP
• Poesía
• Conda
• virtualenv

Comparemos la UV con cada una de estas herramientas para ayudarte a decidir si la UV es la opción adecuada para tus necesidades, antes de entrar en detalles.

UV vs. PIP y virtualenv

PIP y virtualenv han sido las herramientas tradicionales para la gestión de paquetes Python y la creación de entornos virtuales. Aunque cumplen su función, los UV ofrecen varias ventajas convincentes:

• Velocidad: La implementación de Rust de la UV la hace significativamente más rápida que PIP para la instalación de paquetes y la resolución de dependencias, completando a menudo en segundos tareas que a PIP le llevarían minutos.
• Gestión integrada del medio ambiente: Mientras que virtualenv sólo se ocupa de la creación de entornos y PIP sólo de la gestión de paquetes, UV combina ambas funcionalidades en una sola herramienta, agilizando el flujo de trabajo.

UV mantiene la plena compatibilidad con el ecosistema de PIP, al tiempo que aborda sus principales limitaciones. Puede utilizar los mismos archivos requirements.txt e índices de paquetes, lo que hace que la migración sea perfecta. Las principales diferencias son:

• Rendimiento: Las descargas paralelas de UV y la resolución optimizada de dependencias hacen que sea 10-100 veces más rápido que PIP para proyectos grandes.
• Uso de memoria: UV utiliza mucha menos memoria que PIP durante la instalación de paquetes y la resolución de dependencias.
• Tratamiento de errores: UV proporciona mensajes de error más claros y una mejor resolución de conflictos cuando las dependencias chocan.
• Reproducibilidad: El enfoque del archivo de bloqueo de la UV garantiza entornos coherentes en diferentes sistemas, algo que no se garantiza con los archivos básicos de requirements.txt.

Aunque PIP y virtualenv siguen siendo opciones viables, la moderna arquitectura de UV y su funcionalidad combinada la convierten en una alternativa atractiva para los desarrolladores que buscan un mejor rendimiento y un flujo de trabajo más ágil. La capacidad de integrar la UV en proyectos existentes sin alterar los procesos establecidos la hace especialmente atractiva para los equipos que desean modernizar gradualmente su cadena de herramientas de desarrollo en Python.

UV vs. Conda

Las personas que no utilizan PIP y virtualenv suelen recurrir a Conda y tienen buenas razones:

• Conda proporciona una solución completa de gestión de paquetes que no sólo gestiona los paquetes de Python, sino también las dependencias a nivel de sistema
• Destaca en la gestión de entornos informáticos científicos complejos con paquetes como NumPy, SciPy y TensorFlow
• Los entornos Conda están más aislados y son más reproducibles en distintos sistemas operativos
• Tiene soporte incorporado para diferentes versiones de Python y puede cambiar entre ellas fácilmente
• La distribución Anaconda viene con muchos paquetes científicos preinstalados, lo que la hace conveniente para los científicos de datos

Pero incluso los usuarios más acérrimos de Conda deberían plantearse pasarse a UV por varias razones. La rapidísima instalación de paquetes y resolución de dependencias de UV puede acelerar drásticamente la configuración del entorno en comparación con el rendimiento a veces lento de Conda. Su mínima huella de recursos significa menos uso de memoria y arranques más rápidos. UV también se integra perfectamente con los estándares y herramientas de empaquetado de Python existentes, facilitando el trabajo con el ecosistema Python más amplio. Para los proyectos que no requieren la gestión de paquetes no Python de Conda, UV proporciona una solución más ágil y eficaz que puede mejorar significativamente los flujos de trabajo de desarrollo.

UV vs. Poesía

Fui usuario de Conda durante casi tres años, pero después de probar Poesía un par de veces, no volví a tocar Conda a velocidad de tortuga. Justo cuando me estaba sintiendo cómodo con la Poesía, me encontré con la UV y parece que promete casi lo mismo que la Poesía:

• Gestión de la dependencia: Ambas herramientas gestionan eficazmente las dependencias de los paquetes y los entornos virtuales
• Estructura del proyecto: Ambos proporcionan herramientas para inicializar y estructurar proyectos Python
• Bloquear archivos: Ambos generan archivos de bloqueo para garantizar entornos reproducibles
• Paquete editorial: Ambos soportan la publicación de paquetes en PyPI
• Herramientas modernas: Ambos representan enfoques modernos de la gestión de proyectos en Python

Sin embargo, la característica que define a la UV es su rapidísima velocidad y su mínimo uso de recursos. Aunque la Poesía es una mejora significativa respecto a las herramientas tradicionales, la UV lleva el rendimiento a otro nivel gracias a su implementación de Rust. Además, la compatibilidad de UV con los paquetes existentes de Python significa que puede funcionar junto con otras herramientas como pip, ofreciendo una flexibilidad de la que a veces carece el enfoque más opinático de Poetry.

Aquí tienes una tabla que resume las diferencias que acabamos de tratar: 

Si crees que merece la pena cambiar de UV, sigue leyendo.

Primeros pasos con UV para proyectos Python

En esta sección, veremos cómo empezar un proyecto desde cero utilizando UV. Hablaremos de cómo migrar de los proyectos existentes a la UV en una sección posterior.

Instalación de UV

La UV puede instalarse en todo el sistema utilizando cURL en macOS y Linux:

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

Y con Powershell en Windows (asegúrate de ejecutar Powershell con privilegios de administrador):

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

UV también está disponible a través de Homebrew:

$ brew install uv

Se admite la instalación PIP, pero no se recomienda:

$ pip install uv  # Make sure you have a virtual environment activated

Después, puedes verificar la instalación ejecutando uv version:

$ uv version
uv 0.4.25 (97eb6ab4a 2024-10-21)

Inicializar un nuevo proyecto

Trabajar en proyectos es la parte central de la experiencia UV. Empieza por inicializar un proyecto vacío utilizando el comando uv init:

$ uv init explore-uv
Initialized project explore-uv at /Users/bexgboost/projects/explore-uv

El comando creará inmediatamente un nuevo directorio explore-uv con el siguiente contenido:

$ cd explore-uv
$ tree -a
.
├── .gitignore
├── .python-version
├── README.md
├── hello.py
└── pyproject.toml

Git se inicializa automáticamente y se generan los principales archivos relacionados con git, como .gitignore y un archivo vacío README.md. El archivo .python-version contiene la versión de Python utilizada para el proyecto, mientras que pyproject.toml sirve como archivo de configuración principal para los metadatos y dependencias del proyecto. También se crea un archivo hello.py de muestra para ayudarte a empezar rápidamente.

Puedes obtener más información sobre la creación de proyectos en la documentación de la UV.

Añadir dependencias iniciales al proyecto

UV combina la creación del entorno y la instalación de dependencias en un único comando: uv add:

$ uv add scikit-learn xgboost
Using CPython 3.9.20 interpreter at: /opt/homebrew/opt/python@3.9/bin/python3.9
Creating virtual environment at: .venv
Resolved 6 packages in 1.78s
⠧ Preparing packages... (2/5)
Prepared 5 packages in 1m 23s
Installed 5 packages in 45ms
 + joblib==1.4.2
 + numpy==2.0.2
 + scikit-learn==1.5.2
 ...

La primera vez que ejecutas el comando add, la UV crea un nuevo entorno virtual en el directorio de trabajo actual e instala las dependencias especificadas. En las siguientes ejecuciones, la UV reutilizará el entorno virtual existente y sólo instalará o actualizará los nuevos paquetes solicitados, garantizando una gestión eficaz de las dependencias.

Otro proceso importante que ocurre con cada comando de add es la resolución de dependencias. UV utiliza un moderno resolvedor de dependencias que analiza todo el gráfico de dependencias para encontrar un conjunto compatible de versiones de paquetes que satisfagan todos los requisitos. Esto ayuda a evitar conflictos de versiones y garantiza entornos reproducibles. El resolutor tiene en cuenta factores como las restricciones de versión, la compatibilidad de la versión de Python y los requisitos específicos de la plataforma para determinar el conjunto óptimo de paquetes a instalar.

La UV también actualiza los archivos pyproject.toml y uv.lock después de cada comando añadir. Este es el aspecto del archivo TOML después de instalar Scikit-learn y XGBoost:

$ cat pyproject.toml
[project]
name = "explore-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "scikit-learn>=1.5.2",
    "xgboost>=2.0.3",
]

Para eliminar una dependencia del entorno y del archivo pyproject.toml, puedes utilizar el comando uv remove. Desinstalará el paquete y todas sus dependencias hijas:

$ uv remove scikit-learn

Hablaremos de la gestión de dependencias con más detalle en una sección posterior.

Ejecutar scripts Python con UV

Una vez instaladas las dependencias necesarias, puedes empezar a trabajar en tus scripts de Python como de costumbre. UV proporciona algunas formas diferentes de ejecutar código Python:

Para ejecutar directamente un script de Python, puedes utilizar el comando uv run seguido del nombre de tu script en lugar de la sintaxis habitual de python script.py:

$ uv run hello.py

El comando run garantiza que el script se ejecute dentro del entorno virtual UV creado para el proyecto. 

Gestionar las versiones de Python en UV

Gestionar las versiones de Python es una parte clave de la gestión de dependencias. UV proporciona comandos sencillos para controlar qué versión de Python utilizas. Exploremos cómo utilizar el comando uv python.

Listado de versiones existentes de Python

Como es habitual que los sistemas tengan Python ya instalado, la UV puede descubrir estas instalaciones existentes por defecto. Por ejemplo, para listar todas las versiones de Python que UV detecta en tu sistema, ejecuta el siguiente comando:

$ uv python list --only-installed
cpython-3.13.0-macos-aarch64-none     /opt/homebrew/opt/python@3.13/bin/python3.13 -> ../Frameworks/Python.framework/Versions/3.13/bin/python3.13
cpython-3.12.7-macos-aarch64-none     /opt/homebrew/opt/python@3.12/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python3 -> python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python -> python3.12
cpython-3.11.10-macos-aarch64-none    /opt/homebrew/opt/python@3.11/bin/python3.11 -> ../Frameworks/Python.framework/Versions/3.11/bin/python3.11
cpython-3.11.7-macos-aarch64-none     /Users/bexgboost/.local/share/uv/python/cpython-3.11.7-macos-aarch64-none/bin/python3 -> python3.11
cpython-3.10.15-macos-aarch64-none    /opt/homebrew/opt/python@3.10/bin/python3.10 -> ../Frameworks/Python.framework/Versions/3.10/bin/python3.10
cpython-3.9.20-macos-aarch64-none     /opt/homebrew/opt/python@3.9/bin/python3.9 -> ../Frameworks/Python.framework/Versions/3.9/bin/python3.9
cpython-3.9.6-macos-aarch64-none      /Library/Developer/CommandLineTools/usr/bin/python3 -> ../../Library/Frameworks/Python3.framework/Versions/3.9/bin/python3

El comando detectó correctamente mis versiones de Python instaladas en Conda y Brew.

Cambiar las versiones de Python para el proyecto actual 

Puedes cambiar de versión de Python para tu proyecto UV actual en cualquier momento, siempre que la nueva versión satisfaga las especificaciones de tu archivo pyproject.toml. Por ejemplo, el siguiente archivo requiere las versiones 3.9 y superiores de Python:

...
requires-python = ">=3.9"

Esto significa que puedes cambiar la versión de Python en el archivo .python-version a cualquier versión superior, como la 3.11.7. Después, llama a uv sync.

El comando comprueba primero las instalaciones de Python existentes. Si no se encuentra la versión solicitada, la UV la descarga y la instala dentro de la ruta /Users/username/.local/share/uv/python. UV también crea un nuevo entorno virtual dentro del directorio del proyecto, sustituyendo al antiguo. 

Este nuevo entorno no tiene las dependencias que figuran en tu archivo pyproject.toml, por lo que tienes que instalarlas con el siguiente comando:

$ uv pip install -e .

Ten en cuenta que a veces los comandos uv pueden provocar errores Permission Denied. En esos casos, asegúrate de utilizar el comando sudo si estás en macOS o Linux, o ejecuta el símbolo del sistema con privilegios de administrador si estás en Windows. Una solución aún mejor sería cambiar la propiedad del directorio personal de la UV al usuario:

$ sudo chown -R $USER ~/.local/share/uv  # macOS or Linux

Para saber más sobre la gestión de versiones de Python con UV, consulta la documentación. 

¿Qué son las herramientas UV y cómo utilizarlas?

Algunos paquetes de Python se exponen como herramientas de línea de comandos, como black para el formateo de código, flake8 para el linting, pytest para las pruebas, mypy para la comprobación de tipos, etc. La UV proporciona dos interfaces especiales para gestionar estos paquetes:

1. Utilizando uv tool run:

$ uv tool run black hello.py

2. Utilizando el comando uvx, más corto y cómodo:

$ uvx black hello.py

Cuando se ejecutan estos comandos, la UV crea un entorno virtual temporal en su caché. La herramienta solicitada se instala y se ejecuta desde allí. En otras palabras, puedes utilizar herramientas de línea de comandos sin instalarlas en el entorno virtual del proyecto, lo que permite una ejecución más rápida y unas dependencias del proyecto más limpias.

Puntos clave sobre las interfaces de ejecución de la herramienta:

• Funciona con cualquier paquete Python que proporcione herramientas de línea de comandos como flake8, mypy, black o pytest
• Los entornos en caché se limpian automáticamente al limpiar la caché de UV
• Los nuevos entornos en caché se crean bajo demanda cuando es necesario
• Perfecto para el uso ocasional de herramientas de desarrollo

Lee la sección Herramientas UV de la documentación para saber más sobre estas interfaces.

¿Qué son los archivos de bloqueo en UV?

Los archivos de bloqueo (uv.lock) son una parte esencial de la gestión de dependencias en la UV. Cuando ejecutas comandos uv add para instalar dependencias, la UV genera y actualiza automáticamente un archivo uv.lock. Este archivo de bloqueo tiene varias finalidades críticas:

• Registra las versiones exactas de todas las dependencias y sus subdependencias que se instalaron.
• Garantiza construcciones reproducibles "bloqueando" las versiones de las dependencias en distintos entornos.
• Ayuda a evitar el "infierno de las dependencias" manteniendo versiones coherentes de los paquetes.
• Acelera las instalaciones, ya que la UV puede utilizar las versiones bloqueadas en lugar de volver a resolver las dependencias.

La UV gestiona el archivo de bloqueo automáticamente: no necesitas editarlo manualmente. El archivo de bloqueo debe confirmarse en el control de versiones para garantizar que todos los desarrolladores utilizan las mismas versiones de las dependencias.

Diferencia entre archivos de bloqueo y requirements.txt

Aunque tanto los archivos de bloqueo como requirements.txt sirven para hacer un seguimiento de las dependencias, tienen propósitos y casos de uso distintos. Los archivos de bloqueo contienen información detallada sobre las versiones exactas de los paquetes y su árbol de dependencias completo, lo que garantiza entornos coherentes en todo el desarrollo. Los archivos requirements.txt son más sencillos, normalmente sólo enumeran las dependencias directas, y son ampliamente compatibles con todas las herramientas Python.

Los archivos de bloqueo son esenciales para el desarrollo, para mantener compilaciones reproducibles y evitar conflictos de dependencias. Los archivos requirements.txt son más adecuados para escenarios de despliegue o cuando se comparte código con usuarios que pueden no utilizar la UV. También son necesarios para la compatibilidad con herramientas y servicios que no admiten el formato de archivo de bloqueo UV.

Puedes mantener ambos archivos utilizando el archivo de bloqueo de la UV para el desarrollo, mientras generas un requirements.txt para la implantación. Para generar un requirements.txt a partir de un archivo de bloqueo UV, utiliza el siguiente comando:

$ uv export -o requirements.txt

Esto crea el archivo de texto con versiones ancladas basado en tu archivo de bloqueo, lo que facilita compartir las dependencias de tu proyecto en un formato estándar sin dejar de beneficiarte de la gestión avanzada de dependencias de UV durante el desarrollo.

Puedes obtener más información sobre la gestión de archivos de bloqueo en la documentación. 

Gestión avanzada de la dependencia con UV

En esta sección, exploraremos métodos más sofisticados para gestionar las dependencias en UV. Aprenderemos a actualizar las dependencias, hacerlas opcionales o hacerlas parte de un grupo de dependencias.

Actualizar dependencias

En los proyectos a largo plazo, es habitual actualizar los paquetes que utilizas para poner sobre la mesa las características más actuales. O, a veces, un paquete que estás utilizando introduce cambios de última hora y quieres asegurarte de que esa versión no se instala accidentalmente en tu entorno. El comando add puede volver a utilizarse en estos y en cualquier otro escenario en el que necesites cambiar las restricciones o versiones de las dependencias existentes.

1. Instalar la última versión de un paquete:

$ uv add requests

2. Instalar una versión concreta:

$ uv add requests=2.1.2

3. Cambia los límites de las restricciones de un paquete:

$ uv add 'requests<3.0.0'

4. Haz que una dependencia sea específica de una plataforma:

$ uv add 'requests; sys_platform="linux"' 

Añadir dependencias opcionales

Las dependencias opcionales son paquetes que no son necesarios para la funcionalidad básica de tu proyecto, pero que pueden ser necesarios para funciones específicas. Por ejemplo, Pandas tiene un extra excel y un extra plot para evitar la instalación de analizadores Excel y matplotlib a menos que alguien los requiera explícitamente. Los opcionales suelen instalarse con la sintaxis pip install pandas[plot, excel]. 

Con UV, esta sintaxis es ligeramente diferente. En primer lugar, asegúrate de que está instalado el paquete principal de Pandas:

$ uv add pandas

Después, añade sus dependencias opcionales:

$ uv add pandas --optional plot excel

Una vez resueltos, aparecerán en tu pyproject.toml con el siguiente formato:

[project]
name = "explore-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "pandas>=2.2.3",
    "requests>=2.32.3",
]
[project.optional-dependencies]
plot = [
    "excel>=1.0.1",
    ...
]

Grupos de dependencia

Los grupos de dependencias te permiten organizar tus dependencias en grupos lógicos, como dependencias de desarrollo, dependencias de prueba o dependencias de documentación. Esto es útil para mantener tus dependencias de producción separadas de las de desarrollo.

Para añadir una dependencia a un grupo concreto, utiliza la bandera --group:

$ uv add --group group_name package_name

Después, los usuarios podrán controlar qué grupos instalar utilizando las etiquetas --group, --only-group y --no-group.

Cambiar de PIP y Virtualenv a UV

Migrar de PIP y virtualenv a UV es sencillo, ya que UV mantiene la compatibilidad con los estándares de empaquetado de Python existentes. Aquí tienes una guía paso a paso para que la transición sea suave:

1. Convertir un proyecto virtualenv existente

Si ya tienes un proyecto que utiliza virtualenv y pip, empieza por generar un archivo requirements.txt desde tu entorno actual, si aún no lo has hecho:

$ pip freeze > requirements.txt

A continuación, crea un nuevo proyecto UV en el mismo directorio:

$ uv init .

Por último, instala las dependencias de tu archivo de requisitos:

$ uv pip install -r requirements.txt

2. Sustitución de comandos pip/virtualenv comunes

Aquí tienes una referencia rápida para sustituir los comandos comunes pip y virtualenv por sus equivalentes UV:

Tras la migración, puedes eliminar con seguridad tu antiguo directorio virtualenv y empezar a utilizar la gestión de entornos virtuales de UV. La transición suele ser perfecta, y siempre puedes volver a los comandos de pip a través de la capa de compatibilidad de UV pip si es necesario.

Conclusión

UV representa un avance significativo en la gestión de paquetes de Python, ya que ofrece una alternativa moderna, rápida y eficaz a las herramientas tradicionales. Sus principales ventajas son:

• Rendimiento rapidísimo con mejoras de velocidad de 10-100x sobre pip
• Integración perfecta con las normas de empaquetado de Python existentes
• Gestión integrada del entorno virtual
• Resolución eficaz de dependencias y compatibilidad con archivos de bloqueo
• Bajo consumo de memoria y recursos

Tanto si estás empezando un nuevo proyecto como si estás migrando uno existente, la UV proporciona una solución robusta que puede mejorar significativamente tu flujo de trabajo de desarrollo en Python. Su compatibilidad con las herramientas existentes hace que sea una elección fácil para los desarrolladores que buscan modernizar su cadena de herramientas sin alterar sus procesos actuales.

A medida que el ecosistema de Python sigue evolucionando, herramientas como UV demuestran cómo tecnologías modernas como Rust pueden mejorar la experiencia de desarrollo manteniendo la simplicidad y accesibilidad que valoran los desarrolladores de Python.

Si quieres saber más sobre la gestión de dependencias o sobre Python en general, consulta estas fuentes adicionales:

• Tutorial de Python para principiantes
• Tutorial PIP Python: Guía definitiva
• Curso de Desarrollo de Paquetes Python
• Las 9 mejores alternativas a Anaconda para la gestión del entorno Python
• Científico de Datos en Python | Aprende Python para la Ciencia de Datos
• Poesía Pitón: Entorno Python Moderno Y Eficaz Y Gestión De Dependencias