Tutorial de introducción a uv -- Herramienta de gestión de paquetes y entornos de Python

En el desarrollo con Python, la gestión de paquetes y el aislamiento de entornos son problemas que todo desarrollador encuentra. Ya sea la lentitud de pip, lo engorroso de virtualenv o la pesadez de conda,uvtodo hace que los desarrolladores esperen una solución más eficiente.

¿Qué es uv?

uv es un gestor de paquetes y entornos de Python desarrollado por la empresa Astral y escrito en Rust. Su objetivo principal es ofrecer un rendimiento de 10 a 100 veces más rápido que las herramientas existentes, manteniendo al mismo tiempo una experiencia de usuario simple e intuitiva.

uv puede reemplazar herramientas como pip, virtualenv, pip-tools y pyenv, ofreciendo un servicio integral que incluye gestión de dependencias, creación de entornos virtuales y gestión de versiones de Python.

Ventajas de uv

  • Velocidad extrema: Debido a que está escrito en Rust, el rendimiento de uv supera con creces al de pip y otras herramientas de gestión de paquetes; la velocidad de instalación de dependencias puede mejorar de 10 a 100 veces.
  • Integración de funciones: Integra la resolución de dependencias, la instalación de paquetes, la gestión de entornos y la gestión de versiones de Python en una sola herramienta, sin necesidad de instalar y aprender múltiples herramientas.
  • Construcción determinista: uv generará unuv.lockarchivo, lo que garantiza que se puedan instalar exactamente las mismas versiones de dependencias en cualquier entorno, evitando el problema de "en mi máquina funciona".
  • Compatibilidad con herramientas existentes: uv puede manejarrequirements.txtypyproject.toml, y puede reemplazar sin problemas a pip en los flujos de trabajo existentes.

Instalación de uv

Instalación en macOS

Se recomienda instalarlo con Homebrew:

brew install uv

O usar el script de instalación oficial:

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

Instalación en Linux

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

Instalación en Windows

Usando Winget:

winget install uv

O usar el script de instalación oficial (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Después de la instalación, verifica si se realizó correctamente:

uv --version

Una salida similar a la siguiente indica que la instalación fue exitosa:

uv 0.8.14 (Homebrew 2025-08-28)

1. Gestión de versiones de Python

uv tiene incorporada la gestión de versiones de Python, sin necesidad de instalar herramientas adicionales como pyenv.

Ver las versiones disponibles de Python:

uv python list

El resultado es similar al siguiente:

cpython-3.14.0rc2-macos-aarch64-none                 <download available>
cpython-3.13.7-macos-aarch64-none                    <download available>
cpython-3.12.11-macos-aarch64-none                   <download available>
cpython-3.11.13-macos-aarch64-none                   <download available>
cpython-3.10.18-macos-aarch64-none                   <download available>
cpython-3.9.6-macos-aarch64-none                     /usr/bin/python3
pypy-3.11.13-macos-aarch64-none                      <download available>

Instalar una versión específica de Python:

# 安装最新的 Python 3.12
uv python install 3.12

# 安装特定版本
uv python install 3.11.6

# 安装 PyPy 版本
uv python install pypy3.10

Establecer la versión de Python predeterminada global:

uv python default 3.12

Fijar la versión de Python para el proyecto actual (se creará un archivo.python-version):

uv python pin 3.12

Después de ejecutar este comando, se generará un archivo .python-version en el proyecto actual. Al abrirlo, se mostrará el contenido del número de versión:

3.12

2. Gestión de entornos virtuales

Crear un entorno virtual:

# 在当前目录创建名为 .venv 的虚拟环境（使用系统默认 Python）
uv venv

# 使用指定 Python 版本创建虚拟环境
uv venv --python 3.12

Activar el entorno virtual:

# macOS / Linux
source .venv/bin/activate

# Windows（PowerShell）
.venv\Scripts\activate

Salir del entorno virtual:

deactivate

En el desarrollo diario se puede usaruv runpara ejecutar scripts directamente, sin necesidad de activar manualmente el entorno virtual.

3. Gestión de paquetes (modo compatible con pip)

uv proporciona una interfaz de comandos totalmente compatible con pip, que puede reemplazar directamente los comandos de pip en los flujos de trabajo existentes:

Instalar paquetes:

# 安装最新版本
uv pip install requests

# 安装特定版本
uv pip install requests==2.31.0

# 从 requirements.txt 批量安装
uv pip install -r requirements.txt

Actualizar paquetes:

uv pip install --upgrade requests

Desinstalar paquetes:

uv pip uninstall requests

Ver los paquetes instalados:

uv pip list

Exportar las dependencias del entorno actual a requirements.txt:

uv pip freeze > requirements.txt

4. Gestión de proyectos (método recomendado)

uv admite un enfoque moderno de gestión de proyectos centrado enpyproject.toml, lo cual es un método de uso más recomendado que el modo pip, especialmente adecuado para la colaboración en equipo y el despliegue en múltiples entornos.

Inicializar un proyecto

uv init my_project
cd my_project

Esto creará la siguiente estructura básica de proyecto:

my_project/
├── pyproject.toml    # 项目配置和依赖声明
├── .python-version   # 固定 Python 版本
├── README.md
└── main.py

Agregar y eliminar dependencias

En el modo de proyecto, se recomienda usaruv addyuv removepara gestionar las dependencias, y se actualizarán automáticamentepyproject.tomlyuv.lock：

# 添加生产依赖
uv add requests

# 添加指定版本的依赖
uv add "requests>=2.31.0"

# 添加开发依赖（只在开发环境使用，如测试框架）
uv add --dev pytest ruff

# 移除依赖
uv remove requests

Instalar todas las dependencias del proyecto (uv sync)

Después de clonar un proyecto o actualizarpyproject.toml, ejecuta el siguiente comando para instalar todas las dependencias con un solo clic:

uv sync

Explicación de uv sync:Similar apip install -r requirements.txt, segúnpyproject.tomlyuv.lockinstalará todas las dependencias para garantizar que el entorno sea exactamente el mismo que el de otros desarrolladores. Si la instalación es lenta, se puede configurar un espejo doméstico enpyproject.toml:

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

Generar/actualizar el archivo de bloqueo

uv lock

Este comando analizará las dependencias enpyproject.tomly generará (o actualizará) el archivouv.lock.uv.lockDebe enviarse al repositorio de versiones para garantizar que todos los miembros del equipo utilicen exactamente las mismas versiones de dependencias.

5. Ejecutar scripts (uv run)

uv runes un comando muy práctico en uv que permite, sin necesidad de activar manualmente el entorno virtual,ejecutar scripts o comandos directamente; uv encontrará y usará automáticamente el entorno correcto:

# 直接运行 Python 脚本
uv run main.py

# 运行项目中的测试
uv run pytest

# 运行任意命令（在虚拟环境的上下文中执行）
uv run python -c "import requests; print(requests.__version__)"

El uso deuv runen comparación con la activación manual del entorno tiene la ventaja de que no se utilizará por error una versión incorrecta de Python, ni se olvidará de activar el entorno y no se encuentren los paquetes. Es especialmente adecuado para CI/CD y automatización de scripts.

Migrar a uv

Si estás utilizando otras herramientas, puedes migrar a uv de la siguiente manera:

Migrar desde pip + virtualenv:

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装原有依赖
uv pip install -r requirements.txt

Migrar desde pip-tools:

# 编译依赖（替代 pip-compile）
uv pip compile requirements.in -o requirements.txt

# 同步环境（替代 pip-sync）
uv pip sync requirements.txt

Migrar desde poetry o pdm:

# 直接使用现有的 pyproject.toml
uv sync
Otras extensiones