Cómo cambiar de pip a uv en 2026: una guía práctica de migración

Para cambiar de pip a uv, instala el binario de uv y luego reemplaza tus comandos habituales uno por uno: uv venv en lugar de python -m venv, uv add en lugar de pip install y uv run en lugar de activar un entorno virtual a mano. uv es una única herramienta basada en Rust de Astral (el equipo detrás del linter Ruff) que agrupa pip, virtualenv, pip-tools, pipx y pyenv en un solo comando, y los propios benchmarks de Astral la sitúan entre 10 y 100 veces más rápida que pip en las instalaciones con la caché caliente. Esta guía cubre los comandos exactos, una chuleta completa de pip a uv, cómo migrar un proyecto existente y los casos en los que todavía no deberías cambiar.

¿Qué es uv y por qué cambiar desde pip?

uv es un gestor de paquetes y proyectos de Python escrito en Rust cuyo objetivo es ser un reemplazo único de toda una pila de herramientas más antiguas. La documentación de uv lo describe como "una única herramienta para reemplazar pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv y más". La propuesta es velocidad y consolidación: en lugar de recordar qué herramienta crea entornos, cuál bloquea las dependencias y cuál gestiona las versiones de Python, usas uv para todo, y las instalaciones que tardaban decenas de segundos con pip a menudo terminan en menos de un segundo una vez que la caché está caliente.

La velocidad proviene de un descargador en paralelo, una caché global de contenido direccionable que enlaza los paquetes mediante hard links en lugar de volver a descargarlos, y un resolvedor que hace los cálculos de dependencias más rápido que el de pip. Para un script individual la diferencia es agradable; para pipelines de CI y builds de Docker que reinstalan las dependencias en cada ejecución, se acumula en minutos reales ahorrados por build. Por eso uv pasó de ser una curiosidad en 2024 a, según un artículo de un desarrollador de 2026, el gestor de paquetes de Python de referencia para proyectos nuevos.

Instala uv sin romper tu configuración actual

uv se instala como un binario independiente, de modo que convive con tu Python y pip existentes en lugar de reemplazarlos. En macOS o Linux:

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

En Windows (PowerShell):

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

También puedes obtenerlo desde Homebrew (brew install uv), pipx o el propio pip. Tras la instalación, ejecuta uv --version para confirmarlo y uv self update para actualizarlo más adelante. Nada de lo relacionado con la instalación de uv toca tu Python del sistema, tus entornos virtuales existentes ni tu pip global, así que puedes adoptarlo proyecto a proyecto y volver atrás en cualquier momento simplemente retomando tus comandos anteriores.

La chuleta de comandos de pip a uv

Gran parte de la migración es memoria muscular. Esta tabla asocia los comandos que ya conoces con sus equivalentes en uv:

Tarea	pip / herramienta heredada	Equivalente en uv
Crear un entorno virtual	python -m venv .venv	uv venv
Añadir una dependencia a un proyecto	pip install requests	uv add requests
Instalar desde un archivo de requisitos	pip install -r requirements.txt	uv pip install -r requirements.txt
Eliminar una dependencia	pip uninstall requests	uv remove requests
Bloquear versiones exactas	pip freeze > requirements.txt	uv lock (escribe uv.lock)
Reproducir el entorno bloqueado	pip install -r requirements.txt	uv sync
Ejecutar un script en el entorno	source .venv/bin/activate && python app.py	uv run app.py
Instalar una herramienta de CLI globalmente	pipx install ruff	uv tool install ruff
Ejecutar una herramienta una sola vez, sin instalar	pipx run black .	uvx black .
Instalar una versión de Python	pyenv install 3.12	uv python install 3.12
Fijar la versión de Python del proyecto	pyenv local 3.12	uv python pin 3.12

El único hábito que vale la pena abandonar es la activación manual. uv run resuelve y activa el entorno correcto automáticamente, de modo que source .venv/bin/activate pasa a ser opcional. uv también mantiene una interfaz compatible con pip bajo uv pip para los casos en los que quieras un reemplazo casi directo sin adoptar el flujo de trabajo completo de proyectos.

Migra un proyecto existente paso a paso

Para un proyecto que actualmente usa un requirements.txt, el cambio lleva unos pocos minutos:

1. Inicializa uv en el proyecto. Ejecuta uv init en la raíz del proyecto. Esto crea un pyproject.toml (el estándar moderno para declarar dependencias) sin sobrescribir tu código.
2. Importa tus dependencias existentes. Ejecuta uv add -r requirements.txt para leer cada paquete fijado del archivo antiguo y registrarlo en pyproject.toml, y luego resolverlo e instalarlo.
3. Confirma el archivo de bloqueo. uv escribe uv.lock, un archivo de bloqueo multiplataforma que fija todo el grafo de dependencias. Confirma tanto pyproject.toml como uv.lock para que los compañeros de equipo y el CI instalen exactamente las mismas versiones.
4. Cambia tus comandos de ejecución. Reemplaza python script.py por uv run script.py y, en CI, reemplaza el paso de instalación con pip por uv sync --frozen (que falla si el archivo de bloqueo está desactualizado, detectando la deriva antes del despliegue).
5. Elimina los archivos antiguos cuando todo esté en verde. Una vez que el CI pase con uv, puedes eliminar requirements.txt y cualquier requirements-dev.txt, trasladando las herramientas de desarrollo a un grupo de dependencias en pyproject.toml.

La guía de proyectos de Astral documenta cada uno de estos pasos en detalle, incluido cómo estructurar los grupos de dependencias opcionales y de desarrollo.

Gestión de versiones de Python con uv (adiós, pyenv)

uv puede instalar y cambiar intérpretes de Python por sí mismo, que es la característica que le permite jubilar a pyenv. uv python install 3.12 descarga una build independiente de CPython 3.12; uv python list muestra lo que hay instalado y disponible; y uv python pin 3.12 escribe un archivo .python-version para que el proyecto siempre use ese intérprete. Según la guía de gestión de Python de Astral, uv incluso instalará automáticamente una versión requerida de Python la primera vez que ejecutes un proyecto que la necesite, de modo que un nuevo colaborador puede clonar un repositorio y ejecutar uv sync sin instalar Python por separado antes. Ese único comportamiento elimina uno de los fallos de incorporación más comunes en los equipos de Python.

Ejecutar scripts y herramientas: uv run y uvx

Dos comandos cubren la mayor parte del trabajo del día a día. uv run ejecuta un comando dentro del entorno del proyecto, creando o actualizando ese entorno primero si es necesario, de modo que uv run pytest siempre se ejecuta contra las dependencias bloqueadas sin ningún paso de activación. uvx (abreviatura de uv tool run) ejecuta una herramienta de CLI en un entorno desechable sin instalarla en tu proyecto, de modo que uvx ruff check . analiza tu código usando Ruff aunque Ruff no sea una dependencia del proyecto. Para las herramientas que usas constantemente, uv tool install ruff las coloca en tu PATH de forma permanente, reemplazando a pipx. uv también admite dependencias de script en línea, de modo que un script de un solo archivo puede declarar sus propios requisitos en un bloque de comentarios y ejecutarse con uv run script.py, construyendo uv un entorno temporal sobre la marcha.

Trampas y cuándo aún no conviene cambiar

uv es lo bastante rápido y estable para producción, pero es honesto sobre estar en fase pre-1.0: a finales de agosto de 2026 la última versión es la 0.12.5, y el proyecto no ha lanzado una 1.0. En la práctica, eso significa cambios ocasionales que rompen la compatibilidad entre versiones menores, así que fija tu versión de uv en CI (uv publica una GitHub Action e imágenes de Docker para esto) en lugar de traer siempre la última. Algunas otras cosas que sopesar antes de cambiar:

• Equipos con Poetry o PDM. Si tu proyecto ya usa Poetry con un poetry.lock que funciona, el beneficio es menor y la migración es más laboriosa que el cambio desde un simple requirements.txt. Cambia cuando la velocidad te importe, no de forma refleja.
• conda / pilas científicas. uv apunta al ecosistema de PyPI. Si dependes de conda para paquetes científicos compilados o dependencias no Python, uv no reemplaza a conda, y mezclar ambos requiere cuidado.
• Índice y espejos corporativos. Apunta uv a un índice privado con UV_INDEX_URL o la configuración de pyproject.toml antes de desplegarlo en una red interna, del mismo modo que configurarías pip.
• El archivo de bloqueo no es opcional. El beneficio de reproducibilidad solo se materializa si confirmas uv.lock y usas uv sync --frozen en CI. Saltarte eso no te deja en mejor posición que las instalaciones sueltas con pip.

Adóptalo primero en un proyecto paralelo nuevo, siente la velocidad y luego llévalo a tus repositorios principales. Si contenerizas tus builds, combinar uv con una imagen base ligera acumula el beneficio, la misma lógica de reproducibilidad que hay detrás de nuestro análisis de Podman frente a Docker y que vale la pena configurar junto con un flujo de trabajo limpio de git worktrees para ramas en paralelo. Los equipos que automatizan builds en modo headless también lo querrán en cualquier pipeline de CI o de agentes con scripts.

Preguntas frecuentes

¿Cómo ejecuto un archivo de Python usando uv? Usa uv run app.py. uv resuelve las dependencias del proyecto, crea o actualiza el entorno virtual si es necesario y ejecuta el archivo dentro de él, así que nunca tienes que activar el entorno a mano. Para una herramienta puntual, usa uvx <herramienta> para ejecutarla en un entorno temporal.

¿Todavía necesito activar mi venv con uv? No. uv run y uv sync operan automáticamente sobre el .venv del proyecto. Aún puedes usar source .venv/bin/activate si prefieres una sesión de shell tradicional, y uv venv crea un entorno virtual estándar que se activa de la misma manera, pero la activación es opcional para el trabajo normal.

¿Es seguro usar uv en producción? uv se usa ampliamente en producción en 2026 y cuenta con el respaldo de Astral, pero todavía está en fase pre-1.0 (0.12.5 en el momento de escribir esto), así que fija una versión exacta de uv en CI y lee el changelog antes de actualizar. Las builds de Python que instala son distribuciones independientes de CPython, no forks personalizados.

¿Cómo uso uv Python en VS Code? Ejecuta uv sync para crear el .venv, luego en VS Code abre la paleta de comandos, elige "Python: Select Interpreter" y selecciona el intérprete dentro de la carpeta .venv de tu proyecto. VS Code usará entonces el entorno de uv para ejecutar, depurar y analizar el código.

Sources

• Astral — documentación de uv: el benchmark de "10 a 100 veces más rápido que pip" y la lista de herramientas que uv reemplaza.
• Astral — guía de trabajo en proyectos: uv init, uv add, archivos de bloqueo y grupos de dependencias.
• Astral — Instalar y gestionar Python: cómo uv instala y fija las versiones de Python.
• Versiones de astral-sh/uv (GitHub): las versiones 0.12.x actuales y el estado pre-1.0.
• Real Python — Gestión de proyectos de Python con uv: un recorrido integral del flujo de trabajo de uv.
• DEV — Por qué uv se convirtió en el gestor de paquetes de Python de referencia en 2026: contexto de adopción y la justificación de la velocidad.