Primeros pasos con uv: configuración de proyectos Python en 2026

Si alguna vez has peleado con pip, venv y pyenv para poner en marcha un proyecto de Python, esta guía de primeros pasos con uv es para ti. uv es un gestor de paquetes y proyectos de Python escrito en Rust por el equipo de Astral (los mismos que están detrás del linter ruff). Desde su lanzamiento en febrero de 2024, ha llegado a ~88.800 estrellas en GitHub y ha sustituido un mosaico de cinco o seis herramientas por un único binario entre 10 y 100 veces más rápido que pip.

En este artículo veremos cómo instalar uv, crear un proyecto de Python desde cero, gestionar dependencias y versiones de Python, compilar y desplegar, y evitar los problemas más comunes con los que suele chocar la gente. Todos los comandos están actualizados a uv 0.12.5 (agosto de 2026).

¿Qué es uv?

uv es un gestor de paquetes y proyectos de Python todo en uno que sustituye a pip, venv, pipx, poetry y pyenv en un único binario de Rust. Usa pyproject.toml (PEP 621) para la configuración y un archivo uv.lock multiplataforma para builds reproducibles.

Diferencias clave:

• Velocidad: entre 10 y 100 veces más rápido que pip gracias a un resolvedor de dependencias escrito en Rust y a una caché agresiva.
• Flujo de trabajo unificado: paquetes, entornos virtuales, versiones de Python, ejecución de scripts y compilación/publicación, todo en una sola herramienta.
• Basado en estándares: usa pyproject.toml (PEP 621) y [dependency-groups] (PEP 735), no archivos de configuración propietarios.
• Sin activación manual: uv run gestiona el entorno virtual automáticamente. Se acabó el source .venv/bin/activate.

Benchmark de velocidad de instalación del gestor de paquetes uv: entre 10 y 100 veces más rápido que pip

Configura tu proyecto de Python con uv

En esta sección instalaremos uv y crearemos un nuevo proyecto de Python desde cero.

Paso 1: Instalar uv

uv no necesita una instalación previa de Python: puede gestionar las versiones de Python por sí mismo. Instálalo directamente (no con pip) para evitar conflictos de dependencias con el Python de tu sistema.

macOS/Linux

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

Esto descarga e instala uv como un binario independiente. Verás una salida como esta:

downloading uv 0.12.5 aarch64-apple-darwin
no checksums to verify
installing to /Users/user/.local/bin
  uv
  uvx
everything's installed!

Windows

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

Verifica la instalación

uv --version

Deberías ver algo como uv 0.12.5. Comprueba también el binario complementario:

uvx --version

Para confirmar que hay versiones de Python gestionadas disponibles:

uv python list

Muestra todas las versiones de CPython que uv puede descargar y gestionar por ti, sin necesidad de un Python del sistema.

source $HOME/.local/bin/env

Para mantener uv actualizado cuando lo instalaste con el instalador independiente:

uv self update

Si usas un Mac y necesitas instalar o actualizar Python por separado, consulta instala y actualiza Python en tu Mac.

Paso 2: Inicializar un proyecto nuevo con uv init

Desde uv 0.12.0 (julio de 2026), uv init crea una aplicación empaquetada por defecto, con una estructura src/, un sistema de build y un punto de entrada de script. Es un cambio importante respecto a versiones anteriores.

uv init my-python-project
cd my-python-project

La estructura del proyecto generado:

my-python-project/
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── src/
    └── my_python_project/
        └── __init__.py

El pyproject.toml ahora incluye un sistema de build y un punto de entrada de script:

[project]
name = "my-python-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

[project.scripts]
my-python-project = "my_python_project:main"

[build-system]
requires = ["uv_build>=0.12.1,<0.13"]
build-backend = "uv_build"

El src/my_python_project/__init__.py contiene una función inicial:

def main():
    print("Hello from my-python-project!")


if __name__ == "__main__":
    main()

Ejecútalo usando el punto de entrada del script:

uv run my-python-project

Deberías ver Hello from my-python-project! impreso en la terminal. Ojo: ejecutas el nombre del punto de entrada, no main.py.

uv init --no-package my-python-project

my-python-project/
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

Paso 3: Configurar un entorno virtual

uv crea un entorno virtual automáticamente al añadir dependencias, pero también puedes crearlo de forma explícita:

uv venv

Esto crea un directorio .venv en la raíz del proyecto. Lo importante: no necesitas activarlo. uv run gestiona el entorno virtual en cada comando:

uv run python -c "print('Running inside the venv')"

Si aun así quieres activarlo manualmente (por ejemplo, para un IDE que lo necesite):

# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

uv venv --clear

Paso 4: Añadir dependencias

La forma más fácil de añadir dependencias es con uv add, que actualiza pyproject.toml y crea/actualiza uv.lock en un solo paso:

uv add requests

Para dependencias solo de desarrollo (tests, linting):

uv add --dev pytest

Esto usa la tabla [dependency-groups] de PEP 735 en pyproject.toml:

[project]
dependencies = [
    "requests",
]

[dependency-groups]
dev = [
    "pytest",
]

También puedes editar pyproject.toml a mano y luego sincronizar:

uv sync

Lee pyproject.toml, resuelve las dependencias e instala todo en .venv. La velocidad es sorprendente: normalmente termina en menos de un segundo.

Para instalaciones solo de producción (omitiendo las dependencias de desarrollo):

uv sync --no-dev

Nota: la sintaxis antigua [tool.uv] dev-dependencies está obsoleta. Usa [dependency-groups] como se muestra arriba.

Paso 5: Escribir y ejecutar código

Con la nueva estructura empaquetada, tu código vive en src/my_python_project/. Edita src/my_python_project/__init__.py:

import requests


def main():
    response = requests.get("https://api.github.com")
    print(response.json())


if __name__ == "__main__":
    main()

Ejecútalo a través del punto de entrada:

uv run my-python-project

O ejecuta Python directamente dentro del entorno del proyecto:

uv run python -c "from my_python_project import main; main()"

Para scripts rápidos de un solo uso con dependencias temporales (sin proyecto):

uv run --with rich python -c "from rich import print; print({'hello': 'world'})"

Paso 6: Gestionar tu proyecto

Actualiza las dependencias a sus últimas versiones compatibles:

uv sync --upgrade

Exporta a requirements.txt (forma moderna, infiere el formato de la extensión):

uv export -o requirements.txt

También puedes exportar al formato de lockfile estándar PEP 751:

uv export -o pylock.toml

Inspecciona el árbol de dependencias:

uv tree

Ejecuta cualquier comando en el entorno del proyecto:

uv run pytest

Paso 7: Gestionar versiones de Python

uv puede descargar y gestionar versiones de Python sin una instalación del sistema. Lista las versiones disponibles:

uv python list

Instala una versión concreta:

uv python install 3.14

Fíjala para tu proyecto:

uv python pin 3.14

Esto escribe la versión en .python-version.

Actualiza a la última versión de parche:

uv python upgrade

uv python upgrade (estable desde uv 0.10.0) actualiza de forma transparente al último parche. Las actualizaciones de nivel patch ocurren automáticamente; las de nivel minor (por ejemplo, de 3.13 a 3.14) nunca son automáticas: tienes que activarlas tú.

A agosto de 2026, Python 3.14 es la versión estable actual (usa el último parche 3.14.x). Python 3.15 está en release candidate.

Dato aparte: el Python free-threaded (sin GIL) está disponible para 3.13+ con uv python install 3.14t, por si quieres experimentar.

Paso 8: Eliminar paquetes con uv

Elimina un paquete de pyproject.toml, .venv y uv.lock con un solo comando:

uv remove requests

Para una dependencia de desarrollo:

uv remove --dev pytest

Tras la eliminación, tu pyproject.toml queda actualizado y el paquete se desinstala del entorno virtual. uv.lock también se actualiza para mantener la reproducibilidad.

Si editas pyproject.toml a mano para quitar una dependencia, ejecuta uv sync después. De lo contrario, uv no la desinstalará de .venv automáticamente. Mejor usa uv remove para mantener todo limpio.

Compilar, publicar y desplegar

Desde uv 0.12.0, uv init crea un proyecto empaquetado por defecto, así que compilar y publicar es el siguiente paso natural.

Compila tu proyecto:

uv build

Esto genera dist/*.whl (wheel) y dist/*.tar.gz (distribución fuente).

Publica en PyPI:

uv publish

Necesitarás un token de API de PyPI. uv publish también admite índices privados.

Reproducibilidad y CI

Sube siempre uv.lock a git. Fija las versiones exactas de las dependencias en todas las plataformas.

En pipelines de CI, usa --frozen para instalar exactamente lo que indica uv.lock (falla si el lockfile fuera a cambiar):

# GitHub Actions example
- uses: astral-sh/setup-uv@v9
- run: uv sync --frozen

Otros flags útiles para CI:

• uv lock --check: verifica que el lockfile está sincronizado con pyproject.toml (basado en código de salida, útil para pre-commit).
• uv sync --check: verifica que .venv coincide con el lockfile.

Docker

La imagen oficial de Docker es ghcr.io/astral-sh/uv. Un build multi-etapa típico:

FROM ghcr.io/astral-sh/uv:latest AS uv
FROM python:3.14-slim

COPY --from=uv /uv /usr/local/bin/uv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY . .
CMD ["uv", "run", "my-python-project"]

Para desplegar en un VPS con Dokploy, consulta Despliega un proyecto Python con uv, Git y Railpack en Dokploy. Si necesitas hosting VPS económico con Hetzner para tus runners de CI o para el despliegue en producción, es lo que yo uso en la mayoría de mis proyectos personales.

Los precios de los VPS subieron en todos los proveedores en 2026: si estás reconsiderando una máquina alquilada, mira qué cambió y cuándo un mini PC sale ganando.

Para una introducción más amplia a Docker y a ejecutar Python en contenedores, consulta ejecuta tu app de Python en Docker.

¿Por qué elegir uv en 2026?

uv ha pasado de ser un instalador de paquetes experimental a una herramienta completa de gestión de proyectos de Python. Con ~88.800 estrellas en GitHub y adopción por parte de grandes proyectos (FastAPI, entre otros), ya es una herramienta de uso generalizado.

La diferencia de velocidad es real: entre 10 y 100 veces más rápido que pip en la instalación y resolución de dependencias. Pero la mayor ventaja es la simplificación del flujo de trabajo. Un único binario sustituye a pip, venv, pipx, poetry y pyenv. El archivo uv.lock te da builds reproducibles sin la fragilidad de los requirements.txt con versiones fijadas.

Para principiantes, uv elimina la fricción de gestionar entornos de Python. Para desarrolladores con experiencia, los flags pensados para CI (--frozen, --locked, --check), las versiones de Python gestionadas y el pipeline integrado de compilación/publicación ahorran tiempo real. Tanto si construyes un pequeño script como si escalas con uno de los mejores frameworks web de Python, uv se ocupa de las herramientas para que tú te centres en el código.

¿Qué sigue?

Ahora que dominas lo básico, aquí tienes más cosas que puedes hacer con uv:

• Ejecución de scripts: ejecuta scripts de Python sueltos sin crear proyectos completos — uv run: ejecuta scripts de Python sin gestionar dependencias
• Texto a voz: crea un script de generación de audio — Texto a voz en Python con uv: crea audio a partir de texto
• Comprobador de URLs: Comprobador masivo de URLs con uv: encuentra enlaces rotos en Python
• Despliegue: Despliega un proyecto Python con uv, Git y Railpack en Dokploy
• Agentes de IA: Primeros pasos con los agentes de Agno: uv, RAG y memoria
• Equipo de investigación con IA: Crea tu equipo de investigación de IA con Agno, Streamlit y uv
• Interfaz web: Crea una interfaz para tu app de Python con FastHTML
• Docker: Ejecuta tu app de Python en Docker

Conclusión

Empezar con uv es sencillo: instala el binario, ejecuta uv init, añade dependencias con uv add y corre todo con uv run. Todo el flujo de trabajo lleva minutos, no la tarde entera que pasarías peleando con pip y venv a mano.

En 2026, uv es la forma más rápida de gestionar proyectos de Python. Se encarga de paquetes, entornos virtuales, versiones de Python, scripts e incluso de la compilación y publicación. Una herramienta, un lockfile, builds reproducibles en cualquier máquina y en CI.

Para mantenerte al día, consulta la documentación oficial en docs.astral.sh/uv o el repositorio de GitHub en github.com/astral-sh/uv.

Instala uv, inicializa un proyecto y comprueba la diferencia por ti mismo.

Solución de problemas y errores comunes

source $HOME/.local/bin/env

uv venv --clear    # removes and recreates .venv
uv venv --force    # for non-venv directories

uv cache dir    # find the cache location
uv cache clean  # reclaim disk space

Preguntas frecuentes