Entrada

uv vs. Poetry: La trampa de la velocidad extrema en Python

Es hasta 66× más rápido, pero reescribir tu lockfile en silencio puede romper tu CI. Por qué los milisegundos no compensan un build roto.

uv vs. Poetry: La trampa de la velocidad extrema en Python
0:00 / 17:18
Más formatos
Diapositiva 1 de 12

1. Mismo commit, dos resultados: para qué sirve el lockfile

Lunes: clonas el proyecto, ejecutas el comando de instalación y los tests pasan. Jueves: otra persona clona el mismo commit, ejecuta el mismo comando y tres tests fallan. No ha cambiado una línea de código: ha cambiado el mundo, porque una dependencia publicó una versión nueva el miércoles y el pyproject.toml decía «cualquier versión por encima de 2.0 vale».

Ese es el problema que resuelven Poetry y uv. La solución tiene dos piezas: una receta (pyproject.toml, con rangos) y un recibo (poetry.lock o uv.lock, con versiones exactas y hashes). Lo interesante no es que ambos escriban el recibo, sino qué hacen cuando la receta y el recibo dejan de coincidir. Ahí es donde se separan, y donde casi todas las comparativas se quedan cortas.

2. 2018: Poetry arregla el desorden

Antes de Poetry, un proyecto Python era un collage: pip para instalar, virtualenv para aislar, pip-tools para fijar versiones, setup.py para empaquetar y twine para publicar. Cada equipo lo hacía a su manera.

Poetry llegó en 2018 y lo reunió todo en una sola interfaz: declarabas las dependencias en pyproject.toml, resolvía, escribía poetry.lock, creaba el entorno, ejecutaba comandos, construía y publicaba. Hizo que los lockfiles fueran normales en Python.

Sus límites también son de época:

  • Es lento. El resolver está escrito en Python y trabaja a fondo los rangos de versiones. Se nota cuando el árbol crece.
  • No instala Python. Para el intérprete necesitas pyenv o el del sistema.
  • No gestiona herramientas sueltas. Para instalar ruff o black globalmente, pipx.
  • Su formato era propio. Hasta la 2.0, los metadatos estaban en [tool.poetry] y no en el [project] estándar.

Ese último punto cambió el 5 de enero de 2025: Poetry 2.0 adoptó PEP 621, así que pyproject.toml ya se lee como en el resto del ecosistema. También empezó a guardar en el lock los grupos y los marcadores de cada paquete, y añadió una opción para que la instalación no vuelva a resolver (installer.re-resolve), que por defecto sigue activada.

3. 2024: uv sustituye a pip, pyenv, pipx y Poetry

uv apareció en febrero de 2024, escrito en Rust por Astral (los de ruff). Nació como un pip rápido y en agosto de 2024 se convirtió en otra cosa: un reemplazo de pip, pip-tools, pipx, pyenv, virtualenv y Poetry a la vez.

Un solo binario cubre:

1
2
3
4
5
uv python install 3.12     # el intérprete
uv init / uv add / uv sync # el proyecto
uvx ruff check .           # una herramienta sin instalarla
uv run script.py           # un script con sus dependencias (PEP 723)
uv build / uv publish      # paquete y publicación

El lock de uv es universal: resuelve para todas las plataformas a la vez, así que un uv.lock generado en Linux incluye las dependencias condicionales de Windows y macOS. Poetry 2.0 también guarda grupos y marcadores en el suyo, pero su instalación vuelve a resolver por defecto con lo que hay en el lock.

La velocidad es real, pero no es magia: el resolver y el instalador son código compilado, descargan en paralelo y mantienen una caché global de la que los entornos enlazan ficheros con enlaces duros en Linux. Diez proyectos que usan pydantic comparten una copia en disco.

4. Qué cubre uv y qué cubre Poetry

Tabla de cobertura: uv cubre instalación de Python, proyecto, herramientas CLI, scripts PEP 723, build y exportación a pylock.toml; Poetry cubre proyecto, build y publish, y depende de pyenv y pipx para el resto

uv no es «un Poetry más rápido»: es una caja de herramientas. Poetry es un gestor de proyecto que hace muy bien su parte.

Para el día a día, el mapa de comandos:

TareaPoetryuv
Crear proyectopoetry newuv init
Añadir dependenciapoetry adduv add
Instalar del lockpoetry installuv sync
Ejecutarpoetry runuv run
Regenerar el lockpoetry lockuv lock
Actualizar versionespoetry updateuv lock --upgrade
Ver el árbolpoetry show --treeuv tree
Construirpoetry builduv build
Publicarpoetry publishuv publish
Herramientas sueltaspipxuvx

La sintaxis es casi la misma; lo que cambia es lo que pasa por debajo.

5. Benchmark: uv resuelve 6 veces más rápido que Poetry

Los benchmarks publicados varían mucho porque miden cosas distintas. Hay comparativas que dan 22,2 segundos frente a 4,0 en una instalación en frío y 2,8 frente a 0,11 al recrear el entorno; esos números incluyen add (resolver, descargar e instalar) y una red concreta.

Yo separé las fases para ver dónde se va el tiempo:

  • Mismo proyecto en los dos casos, con las mismas nueve dependencias directas (fastapi, sqlalchemy, pydantic, httpx, cryptography, marshmallow, loguru, click, websockets): 26 paquetes resueltos.
  • Python 3.12.13 del sistema, Ryzen 7 8745HS, 27 GB de RAM.
  • Caché aislada por herramienta y borrada entre fases frías; el entorno se elimina antes de cada instalación.
  • Tres ejecuciones por fase; se publica la mediana.
FasePoetry 2.5uv 0.13Diferencia
Resolver en frío2,45 s0,39 s6×
Resolver en caliente1,21 s0,02 s66×
Instalar en frío1,47 s0,55 s3×
Instalar en caliente0,86 s0,02 s44×

Gráfico de barras logarítmico con los tiempos de resolver e instalar en frío y en caliente: Poetry tarda 2,45 y 1,21 segundos en resolver y 1,47 y 0,86 en instalar; uv, 0,39 y 0,02 en resolver y 0,55 y 0,02 en instalar

La ventaja de uv no es una constante: va de 3× en el peor caso (descargar de la red) a 66× en el mejor (todo en caché). Por eso dos benchmarks bien hechos pueden dar cifras distintas.

Lo sorprendente está en la primera y la tercera fila. Cuando hay que descargar de verdad, la diferencia se queda en 3×: la red pesa más que el lenguaje. Y cuando la caché está caliente, uv no «instala»: crea enlaces, y el tiempo se vuelve casi cero. Poetry, en cambio, vuelve a resolver al instalar (su installer.re-resolve por defecto) y copia los ficheros en el entorno.

Es la misma lección de siempre: la velocidad no es una propiedad del motor, es una propiedad del trabajo que le pides. Como con Cython y el código Python acelerado, lo que importa es saber qué cuesta cada paso.

5.1 Lo que no mide este benchmark

Un corpus de 26 paquetes con binarios precompilados disponibles no representa a todo el mundo. Si tu dependencia estrella solo publica código fuente, el tiempo se va en compilar y las dos herramientas se acercan: el cuello de botella deja de ser el instalador. Tampoco mide el tiempo de arranque en CI ni el de construir una imagen Docker, donde uv también gana por no necesitar un runtime de Python instalado antes.

Lo que sí deja claro es cómo varía la diferencia: grande cuando hay caché, moderada cuando hay red. Cualquier cifra única («uv es 10 veces más rápido») es un promedio de escenarios que no son el tuyo.

6. uv reescribe el lock; Poetry se niega

Esquema: pyproject con rangos pasa por el resolver y produce un lockfile con versiones exactas; Poetry da error si el lock no cuadra, uv re-resuelve, reescribe y sigue

Las dos herramientas comparten la receta y el recibo. Discrepan en qué hacer cuando no coinciden.

Cambia una dependencia en pyproject.toml y pide a uv que instale con el lock existente:

1
2
3
$ uv sync --locked
error: The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.
hint: To update the lockfile, run `uv lock`.

Hasta aquí, lo esperable. Ahora quita --locked:

1
2
3
4
5
6
7
$ uv sync
Resolved 30 packages in 6ms
Installed 4 packages in 3ms
 + markdown-it-py==4.2.0
 + mdurl==0.1.2
 + pygments==2.21.0
 + rich==15.0.0

uv re-resuelve, reescribe uv.lock y sigue, sin preguntar. En tu portátil es exactamente lo que quieres. En CI es una trampa: si alguien cambió pyproject.toml y olvidó commitear el lock, la máquina de CI lo corrige en su copia de trabajo, el build sale verde y el recibo del repositorio se queda viejo. Nadie se entera hasta que otro clona.

Poetry, con el mismo cambio, hace lo contrario:

1
2
3
4
$ poetry install
Installing dependencies from lock file

pyproject.toml changed significantly since poetry.lock was last generated. Run `poetry lock` to fix the lock file.

La herramienta vieja es la estricta; la moderna, la que facilita las cosas. Y esa diferencia importa más que los milisegundos.

Grabación de terminal

Grabación real: uv con el lock en sincronía, el mismo cambio con --locked (falla), sin --locked (reescribe y sigue) y Poetry con el mismo cambio (se niega).

7. Por qué --locked importa más que la velocidad

En un portátil, que uv actualice el lock es una comodidad. En un pipeline de integración es un contrato roto. El flag convierte una herramienta permisiva en una comprobación:

  • uv sync --locked falla si el lock no coincide con pyproject.toml.
  • uv sync --frozen usa el lock tal cual, sin comprobar nada (para imágenes ya construidas).
  • uv lock --check comprueba sin instalar.

La regla práctica es sencilla: --locked en CI, Docker y release; nada en local. Si el build necesita descargar algo que no está en el lock, mejor que falle a que lo invente.

Poetry no necesita un flag porque su comportamiento por defecto ya es el estricto. Eso no lo hace mejor: lo hace menos sorprendente. Y en un proyecto con releases automatizadas, lo predecible vale más que lo cómodo.

8. pylock.toml: el estándar que casi nadie usa

Hay una vuelta de tuerca más. Durante años, cada herramienta inventó su lockfile: poetry.lock, uv.lock, Pipfile.lock, pdm.lock. Eso ata el proyecto a la herramienta.

En marzo de 2025 se aprobó PEP 751, que define un formato estándar: pylock.toml. Y aquí llega la parte que poca gente conoce: uv puede exportar su lock a ese formato, además de a requirements.txt y a un SBOM CycloneDX:

1
2
uv export --format pylock.toml --output-file pylock.toml
uv export --format cyclonedx1.5 --output-file sbom.json

No es lo mismo que usar pylock.toml de forma nativa —uv sigue trabajando con uv.lock—, pero sí permite que otra herramienta lea tus dependencias exactas o que un auditor reciba un SBOM sin instalar nada. Es la diferencia entre «mi lock es mío» y «mi lock se puede leer».

Merece la pena tenerlo en cuenta si publicas bibliotecas o si tu empresa pide inventario de dependencias: el lock estándar y el SBOM salen de un comando, no de un script casero.

9. Scripts PEP 723, uvx e intérpretes: lo que Poetry no cubre

Hay una capacidad de uv que no tiene equivalente en Poetry y que cambia la forma de compartir código pequeño: los scripts con metadata inline de PEP 723.

1
2
3
4
5
6
7
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///
import httpx

print(httpx.get("https://example.com").status_code)

uv run fetch.py crea un entorno efímero con httpx, ejecuta el script y lo borra. Sin proyecto, sin requirements.txt, sin «¿de qué venv era esto?». uv add --script fetch.py httpx escribe el bloque por ti.

Lo mismo con las herramientas: uvx ruff check . ejecuta ruff en un entorno aislado sin instalarlo, que es el trabajo de pipx. Y uv python install 3.13 descarga y gestiona intérpretes, que es el trabajo de pyenv.

Poetry no intenta cubrir eso, y no es un defecto: es otra filosofía. Para el día a día del lenguaje, la cheatsheet de Python sigue siendo el atajo más rentable. Pero si compartes scripts con el equipo, la diferencia se nota el primer día.

10. Migrar de Poetry a uv sin romper nada

La migración es más corta de lo que parece, pero tiene cuatro trampas.

1. El lock no es el mismo. uv vuelve a resolver desde pyproject.toml; no importa poetry.lock. Si el proyecto llevaba meses sin actualizar, la primera resolución puede subir versiones. Compara antes y después:

1
2
poetry show --tree > antes.txt
uv tree > despues.txt

2. Los grupos de dependencias cambian de sitio. Poetry usa [tool.poetry.group.dev.dependencies]; uv lee [dependency-groups] (PEP 735) o [project.optional-dependencies]. Si el proyecto es antiguo, toca moverlas.

3. La publicación no es un calco. uv build y uv publish existen, y uv_build es un backend propio, pero si publicabas con poetry publish --build y credenciales en poetry config, revisa cómo las pasa uv (variables de entorno o --token).

4. El CI necesita --locked desde el primer commit. Si lo dejas para después, el primer build verde puede estar usando un lock distinto del que está en el repositorio. Es exactamente la trampa de la sección 6.

Un orden que funciona: crear uv.lock, comparar el árbol, ejecutar los tests con uv run, cambiar el CI a uv sync --locked, y solo entonces borrar poetry.lock. Si algo falla, el lock viejo sigue ahí para volver atrás.

11. ¿Poetry o uv? Cuándo elegir cada uno

Elige uv si:

  • Quieres un solo binario para intérprete, proyecto, herramientas y scripts.
  • Tu CI instala muchas veces al día y el tiempo importa.
  • Te gusta que el lock se pueda exportar a un formato estándar o a un SBOM.
  • No te importa añadir --locked a mano en los pipelines.

Elige Poetry si:

  • Ya tienes proyectos con poetry.lock y no quieres migrar 111 versiones bloqueadas.
  • Prefieres que la herramienta te obligue a regenerar el lock en vez de hacerlo sola.
  • Publicas paquetes y quieres un flujo maduro de build y publish.
  • Necesitas las funciones específicas de Poetry que no están en el estándar.

Y si migras, hazlo con el lock delante: compara el árbol resuelto (poetry show --tree con uv tree), comprueba que las versiones son las mismas, ejecuta los tests con el entorno nuevo y añade --locked desde el primer commit. La migración no es difícil; el riesgo está en lo que cambia sin que lo veas.

12. Enlaces y vídeos de interés

12.1 Artículos

12.2 Vídeos

Poetry de principio a fin: proyecto, dependencias, lock y publicación, en un tutorial completo de 2025.

uv frente al flujo clásico de pip y venv, con Corey Schafer: resolución, entornos y herramientas en un solo binario.

Esta entrada está licenciada bajo CC BY 4.0 por el autor.