Python Poetry: Guía moderna de gestión de dependencias y empaquetado

Name

Soren Atelier

Updated on 12/2/2026

Gestionar dependencias en Python no debería ser doloroso. Aun así, cualquier desarrollador de Python ha vivido este escenario: clonas un proyecto, ejecutas pip install -r requirements.txt y observas cómo los conflictos de dependencias se encadenan en tu terminal. El paquete A necesita la versión 1.x de una librería, el paquete B necesita la versión 2.x, y pip instala la que termina resolviendo al final, rompiendo silenciosamente uno de ellos. Luego vienen horas de depuración, todo porque pip carece de un resolvedor de dependencias sólido y de un mecanismo de lock file.

Este problema se agrava en entornos de equipo. Un desarrollador fija versiones exactas, otro usa rangos laxos, y un tercero se olvida de actualizar requirements.txt tras instalar un paquete nuevo. Los despliegues fallan. Los tests pasan en local pero se rompen en CI. La causa raíz siempre es la misma: las herramientas por defecto de Python tratan la gestión de dependencias como algo secundario.

Poetry resuelve esto ofreciendo una única herramienta que maneja la resolución de dependencias, la gestión de entornos virtuales y la publicación de paquetes. Utiliza un archivo estándar pyproject.toml, genera lock files deterministas y resuelve conflictos antes de instalar, no después. Esta guía cubre todo: desde la instalación hasta la publicación, con ejemplos prácticos para cada flujo de trabajo.

¿Qué es Python Poetry?

Poetry es una herramienta open-source para la gestión de dependencias y el empaquetado en Python. Creada por Sebastien Eustace en 2018, aborda el estado fragmentado del empaquetado en Python combinando varias funciones en una única herramienta coherente:

• Resolución de dependencias: Poetry analiza todas las dependencias y sus subdependencias para encontrar versiones compatibles antes de instalar nada.
• Lock files: Un archivo poetry.lock registra las versiones exactas de cada paquete instalado, garantizando builds reproducibles entre máquinas.
• Gestión de entornos virtuales: Poetry crea y gestiona automáticamente entornos virtuales aislados por proyecto.
• Construcción y publicación de paquetes: Poetry construye distribuciones fuente y wheels, y publica directamente en PyPI o en repositorios privados.
• Scaffolding del proyecto: Poetry genera estructuras de proyecto con una configuración pyproject.toml adecuada.

Poetry usa pyproject.toml como archivo de configuración, siguiendo los estándares PEP 518 y PEP 621. Esto reemplaza la combinación de setup.py, setup.cfg, requirements.txt y MANIFEST.in que los proyectos tradicionales de Python suelen requerir.

Instalación de Poetry

Poetry ofrece su propio instalador que lo aísla de las dependencias de tu proyecto, evitando conflictos de versiones entre el propio Poetry y los paquetes del proyecto.

Instalación recomendada (instalador oficial)

Linux, macOS y Windows (WSL):

curl -sSL https://install.python-poetry.org | python3 -

Windows (PowerShell):

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Tras la instalación, añade Poetry a tu PATH. El instalador imprime la ruta exacta — normalmente $HOME/.local/bin en Linux/macOS o %APPDATA%\Python\Scripts en Windows.

Verifica la instalación:

poetry --version

Instalación con pipx

Si prefieres usar pipx (que también aísla herramientas CLI):

pipx install poetry

Actualizar Poetry

poetry self update

Para actualizar a una versión específica:

poetry self update 1.8.0

Habilitar autocompletado con Tab

Poetry soporta autocompletado para Bash, Zsh y Fish:

# Bash
poetry completions bash >> ~/.bash_completion
 
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
 
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish

Crear un nuevo proyecto

Poetry ofrece dos formas de empezar un proyecto: crear uno desde cero o inicializar Poetry en un proyecto existente.

Nuevo proyecto desde cero

poetry new my-project

Esto genera la siguiente estructura:

my-project/
├── pyproject.toml
├── README.md
├── my_project/
│   └── __init__.py
└── tests/
    └── __init__.py

Para un layout de código plano (paquete en la raíz):

poetry new --src my-project

Esto coloca el paquete dentro de un directorio src/:

my-project/
├── pyproject.toml
├── README.md
├── src/
│   └── my_project/
│       └── __init__.py
└── tests/
    └── __init__.py

Inicializar en un proyecto existente

Navega al directorio de tu proyecto existente y ejecuta:

cd existing-project
poetry init

Poetry te guía mediante una configuración interactiva, preguntando el nombre del paquete, versión, descripción, autor, compatibilidad con versiones de Python y dependencias. Puedes pulsar Enter para aceptar valores por defecto u omitir campos opcionales.

Para una configuración no interactiva:

poetry init --name my-package --description "A useful package" --author "Your Name <you@example.com>" --python "^3.9" --no-interaction

Entendiendo pyproject.toml

El archivo pyproject.toml es la única fuente de verdad para la configuración de tu proyecto. Aquí tienes un ejemplo completo:

[tool.poetry]
name = "my-project"
version = "1.0.0"
description = "A data processing library"
authors = ["Your Name <you@example.com>"]
license = "MIT"
readme = "README.md"
homepage = "https://github.com/yourname/my-project"
repository = "https://github.com/yourname/my-project"
keywords = ["data", "processing", "analytics"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries",
]
 
[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.0"
requests = "^2.31"
pydantic = ">=2.0,<3.0"
 
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
mypy = "^1.0"
ruff = "^0.3"
 
[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"
sphinx-rtd-theme = "^2.0"
 
[tool.poetry.scripts]
my-cli = "my_project.cli:main"
 
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Sintaxis de restricciones de versión

Poetry usa una sintaxis clara para restricciones de versión:

La restricción caret (^) es la más común y recomendada. Permite actualizaciones que no cambian el dígito más a la izquierda distinto de cero, siguiendo los principios de semantic versioning.

Grupos de dependencias

Poetry organiza dependencias en grupos, reemplazando la necesidad de archivos requirements separados:

• Dependencias principales ([tool.poetry.dependencies]): necesarias para que el paquete funcione. Se incluyen cuando alguien instala tu paquete.
• Dependencias de desarrollo ([tool.poetry.group.dev.dependencies]): herramientas para desarrollo, tests y linting. No se incluyen en paquetes publicados.
• Grupos personalizados ([tool.poetry.group.docs.dependencies]): cualquier agrupación adicional que necesites, como herramientas de documentación.

Añadir y eliminar dependencias

Añadir paquetes

Añade un paquete a las dependencias principales:

poetry add pandas

Añadir con una restricción de versión:

poetry add "pandas>=2.0,<3.0"

Añadir al grupo de desarrollo:

poetry add --group dev pytest black ruff

Añadir a un grupo personalizado:

poetry add --group docs sphinx

Añadir un paquete desde un repositorio Git:

poetry add git+https://github.com/user/repo.git

Añadir un paquete desde una rama o tag específico:

poetry add git+https://github.com/user/repo.git#branch-name
poetry add git+https://github.com/user/repo.git#v1.0.0

Añadir una dependencia por ruta local:

poetry add ../my-local-package

Añadir extras para un paquete:

poetry add "uvicorn[standard]"

Eliminar paquetes

Eliminar un paquete:

poetry remove pandas

Eliminar de un grupo específico:

poetry remove --group dev black

Listar paquetes instalados

Ver todos los paquetes instalados:

poetry show

Ver detalles de un paquete específico:

poetry show pandas

Mostrar el árbol de dependencias:

poetry show --tree

Mostrar paquetes desactualizados:

poetry show --outdated

El lock file: poetry.lock

El archivo poetry.lock es una de las funciones más importantes de Poetry. Cuando ejecutas poetry install o poetry add, Poetry resuelve todas las dependencias y escribe las versiones exactas (incluyendo todas las dependencias transitivas) en poetry.lock.

Por qué importan los lock files

Sin un lock file, ejecutar pip install -r requirements.txt con restricciones de versión laxas puede producir instalaciones diferentes en distintas máquinas o en momentos distintos. Un lock file elimina esa aleatoriedad.

Considera este escenario:

[tool.poetry.dependencies]
requests = "^2.28"

Esto permite cualquier versión desde 2.28.0 hasta 2.99.x. Sin un lock file, tu servidor de CI podría instalar 2.31.0 mientras tu máquina local usa 2.28.2. El lock file fija la versión exacta en todos los entornos.

Flujo de trabajo con lock file

Haz commit de poetry.lock en el control de versiones. Esto garantiza que cada desarrollador y despliegue use versiones idénticas de paquetes.

git add poetry.lock pyproject.toml
git commit -m "Add project dependencies"

Instala desde el lock file (para instalaciones reproducibles):

poetry install

Esto instala exactamente las versiones especificadas en poetry.lock, ignorando versiones compatibles más nuevas.

Actualiza el lock file cuando quieras versiones más recientes:

# Update all packages
poetry update
 
# Update a specific package
poetry update pandas
 
# Update the lock file without installing
poetry lock

Verifica la integridad del lock file:

poetry lock --check

Esto confirma que el lock file es consistente con pyproject.toml sin modificar nada.

Gestión de entornos virtuales

Poetry crea y gestiona automáticamente entornos virtuales para tus proyectos.

Comportamiento por defecto

Cuando ejecutas poetry install o poetry add, Poetry crea un entorno virtual si no existe. Por defecto, los entornos se guardan en un directorio de caché centralizado:

• Linux: ~/.cache/pypoetry/virtualenvs/
• macOS: ~/Library/Caches/pypoetry/virtualenvs/
• Windows: C:\Users\<user>\AppData\Local\pypoetry\Cache\virtualenvs\

Entornos virtuales dentro del proyecto

Muchos desarrolladores prefieren el entorno virtual dentro del directorio del proyecto (similar a node_modules en Node.js). Configúralo globalmente:

poetry config virtualenvs.in-project true

Esto crea un directorio .venv en la raíz del proyecto, facilitando encontrarlo y siendo compatible con la autodetección de IDEs.

Ejecutar comandos en el entorno virtual

Ejecutar un único comando:

poetry run python my_script.py
poetry run pytest
poetry run black .

Activar el shell del entorno:

poetry shell

Esto abre un nuevo shell con el entorno virtual activado. Sal con exit o Ctrl+D.

Información del entorno

Ver detalles del entorno:

poetry env info

Listar todos los entornos asociados al proyecto:

poetry env list

Usar una versión específica de Python:

poetry env use python3.11

Eliminar un entorno:

poetry env remove python3.11

Instalación de dependencias

Instalación estándar

Instala todas las dependencias (principales y de desarrollo):

poetry install

Instalación para producción

Instalar sin dependencias de desarrollo:

poetry install --without dev

Instalar sin grupos específicos:

poetry install --without dev,docs

Instalar solo grupos específicos

poetry install --only main
poetry install --only dev

Sincronizar el entorno

Eliminar paquetes que no están en el lock file (instalación limpia):

poetry install --sync

Esto elimina cualquier paquete instalado manualmente o que ya no esté en el lock file, manteniendo el entorno exactamente alineado con la configuración del proyecto.

Construir y publicar paquetes

Poetry simplifica todo el flujo de publicación de paquetes.

Construir tu paquete

poetry build

Esto crea tanto una distribución fuente (.tar.gz) como una wheel (.whl) en el directorio dist/:

dist/
├── my_project-1.0.0.tar.gz
└── my_project-1.0.0-py3-none-any.whl

Publicar en PyPI

Primero, configura tus credenciales de PyPI:

poetry config pypi-token.pypi your-api-token

Luego publica:

poetry publish --build

El flag --build construye y publica en un solo paso.

Publicar en un repositorio privado

Añade un repositorio privado:

poetry config repositories.private https://private.pypi.example.com/simple/
poetry config http-basic.private username password

Publica en él:

poetry publish --repository private

Gestión de versiones

Incrementa versiones usando semantic versioning:

poetry version patch    # 1.0.0 -> 1.0.1
poetry version minor    # 1.0.0 -> 1.1.0
poetry version major    # 1.0.0 -> 2.0.0
poetry version prepatch # 1.0.0 -> 1.0.1a0

Mostrar la versión actual:

poetry version

Migrar desde requirements.txt

Si tienes un proyecto existente usando requirements.txt, migrar a Poetry es sencillo.

Paso 1: Inicializar Poetry

cd your-project
poetry init --no-interaction

Paso 2: Añadir dependencias desde requirements.txt

Para un archivo requirements simple:

cat requirements.txt | xargs poetry add

Para archivos con restricciones de versión, añade paquetes manualmente o usa un script de migración:

import subprocess
 
with open("requirements.txt") as f:
    packages = []
    for line in f:
        line = line.strip()
        if line and not line.startswith("#") and not line.startswith("-"):
            packages.append(line)
 
if packages:
    subprocess.run(["poetry", "add"] + packages)

Paso 3: Añadir dependencias de desarrollo

Si tienes un requirements-dev.txt:

cat requirements-dev.txt | xargs poetry add --group dev

Paso 4: Verificar y bloquear

poetry install
poetry lock --check

Paso 5: Limpieza

Tras verificar que todo funciona, puedes eliminar los archivos antiguos:

rm requirements.txt requirements-dev.txt setup.py setup.cfg

Exportar de vuelta a requirements.txt

Si necesitas un requirements.txt por compatibilidad (builds en Docker, sistemas CI legacy):

poetry export -f requirements.txt --output requirements.txt

Incluir dependencias de desarrollo:

poetry export -f requirements.txt --with dev --output requirements-dev.txt

Poetry vs pip vs pipenv vs uv: Comparación

Elegir la herramienta adecuada de gestión de dependencias depende de los requisitos de tu proyecto. Aquí tienes una comparación detallada:

Cuándo elegir cada herramienta

Elige Poetry cuando necesitas una solución completa de empaquetado: gestión de dependencias, construcción y publicación en PyPI en una sola herramienta, con un ecosistema maduro y documentación extensa.

Elige pip para scripts simples, prototipado rápido o cuando trabajas con restricciones que requieren las herramientas estándar. Pip sigue siendo la base sobre la que construyen otras herramientas.

Elige pipenv para aplicaciones web donde necesitas entornos reproducibles pero no publicas paquetes en PyPI. Su formato Pipfile separa claramente dependencias de desarrollo y producción.

Elige uv cuando la velocidad de instalación es prioritaria, o quieres una sola herramienta que también gestione versiones de Python. uv está escrito en Rust y resuelve dependencias de forma significativamente más rápida que herramientas basadas en Python. Es compatible con pip y puede servir como reemplazo directo.

Configuración de Poetry y consejos

Opciones de configuración útiles

# Store virtual environments in the project directory
poetry config virtualenvs.in-project true
 
# Use a specific Python version for new environments
poetry config virtualenvs.prefer-active-python true
 
# Disable automatic virtual environment creation
poetry config virtualenvs.create false
 
# View all configuration
poetry config --list

Poetry con Docker

Un Dockerfile de producción usando Poetry:

FROM python:3.12-slim
 
ENV POETRY_VERSION=1.8.0 \
    POETRY_HOME="/opt/poetry" \
    POETRY_VIRTUALENVS_CREATE=false \
    POETRY_NO_INTERACTION=1
 
RUN pip install poetry==$POETRY_VERSION
 
WORKDIR /app
 
COPY pyproject.toml poetry.lock ./
RUN poetry install --without dev --no-root
 
COPY . .
RUN poetry install --without dev
 
CMD ["python", "-m", "my_project"]

Puntos clave:

• POETRY_VIRTUALENVS_CREATE=false evita crear un entorno virtual dentro del contenedor (el contenedor ya proporciona aislamiento).
• Instala dependencias antes de copiar el código fuente para aprovechar el caching por capas de Docker.
• Ejecuta poetry install dos veces: primero sin el proyecto (solo dependencias), y luego con el proyecto.

Poetry con CI/CD

Ejemplo de GitHub Actions:

name: CI
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install Poetry
        run: pip install poetry
      - name: Install dependencies
        run: poetry install
      - name: Run tests
        run: poetry run pytest
      - name: Run linting
        run: poetry run ruff check .

Poetry en flujos de trabajo con Jupyter

Los data scientists suelen trabajar en notebooks de Jupyter, donde la gestión de dependencias es especialmente importante. Poetry se integra bien con Jupyter asegurando que los notebooks usen el entorno correcto.

Instala Jupyter dentro de tu proyecto Poetry:

poetry add --group dev jupyter ipykernel

Registra el entorno de Poetry como un kernel de Jupyter:

poetry run python -m ipykernel install --user --name=my-project

Lanza Jupyter desde dentro del entorno Poetry:

poetry run jupyter notebook

Para una experiencia de Jupyter más fluida con gestión automática de dependencias y asistencia con IA, RunCell (opens in a new tab) ofrece un entorno integrado donde puedes centrarte en el análisis en lugar de la configuración del entorno. RunCell gestiona automáticamente la instalación de paquetes y la gestión de kernels, lo que complementa el control de dependencias a nivel de proyecto de Poetry.

Referencia de comandos comunes de Poetry

Resolución de problemas comunes

Fallos en la resolución de dependencias

Problema: Poetry no puede encontrar un conjunto compatible de versiones.

SolverProblemError: ...unable to find compatible versions...

Solución: Relaja las restricciones de versión o revisa requisitos en conflicto:

# Show what conflicts exist
poetry show --tree
 
# Try with a wider constraint
poetry add "problematic-package>=1.0"

Resolución lenta

Problema: poetry lock tarda mucho.

Solución: Poetry cachea metadatos de paquetes, pero la primera resolución en un proyecto con muchas dependencias puede ser lenta. Si la resolución supera varios minutos:

# Clear the cache and retry
poetry cache clear --all pypi
 
# Use verbose output to see what is happening
poetry lock -vvv

El entorno virtual no es detectado por el IDE

Problema: VS Code o PyCharm no encuentra el entorno de Poetry.

Solución: Configura entornos virtuales dentro del proyecto:

poetry config virtualenvs.in-project true
poetry install  # Recreates .venv in project root

Luego selecciona .venv/bin/python como intérprete en tu IDE.

Errores de hash mismatch

Problema: poetry install reporta discrepancias de hash.

Solución: Regenera el lock file:

poetry lock --no-update

Esto regenera hashes sin cambiar versiones de dependencias.

FAQ

¿Para qué se usa Python Poetry?

Python Poetry es una herramienta de gestión de dependencias y empaquetado que se encarga de instalar paquetes, resolver conflictos de versiones, gestionar entornos virtuales y publicar paquetes en PyPI. Reemplaza la combinación de pip, venv, setuptools y twine con una herramienta unificada centrada en el archivo de configuración pyproject.toml.

¿Poetry es mejor que pip?

Poetry y pip tienen propósitos distintos. Poetry ofrece resolución de dependencias, lock files, gestión de entornos virtuales y publicación de paquetes en una sola herramienta. Pip es más simple y funciona bien para instalaciones directas. Para proyectos que requieren builds reproducibles, colaboración en equipo o publicación de paquetes, Poetry ofrece ventajas significativas. Para scripts rápidos o proyectos simples, pip sigue siendo suficiente.

¿Cómo cambio de pip a Poetry?

Inicializa Poetry en tu proyecto con poetry init, y luego añade tus dependencias desde requirements.txt usando cat requirements.txt | xargs poetry add. Poetry crea un archivo pyproject.toml y un poetry.lock. Tras verificar que todo funciona con poetry install, puedes eliminar el archivo requirements.txt antiguo. Usa poetry export si aún necesitas requirements.txt por compatibilidad.

¿Poetry reemplaza virtualenv?

Sí. Poetry crea y gestiona automáticamente entornos virtuales para cada proyecto. No necesitas crear o activar entornos manualmente. Poetry guarda los entornos en una caché centralizada por defecto, o en el directorio del proyecto si lo configuras con poetry config virtualenvs.in-project true. Aun así, puedes usar poetry shell para activar el entorno de forma interactiva.

¿Puede Poetry gestionar múltiples versiones de Python?

Poetry en sí no instala versiones de Python, pero funciona con las versiones de Python disponibles en tu sistema. Usa pyenv o uv para instalar múltiples versiones de Python, y luego indica a Poetry cuál usar con poetry env use python3.11. Poetry crea entornos virtuales separados para distintas versiones de Python dentro del mismo proyecto.

¿Cuál es la diferencia entre poetry.lock y requirements.txt?

Un archivo poetry.lock registra cada paquete instalado y su versión exacta, incluyendo todas las dependencias transitivas, junto con hashes de contenido para verificación. Un requirements.txt generado con pip freeze también lista versiones exactas, pero no incluye verificación por hashes ni seguimiento de relaciones de dependencias. El lock file garantiza instalaciones deterministas en todos los entornos, mientras que requirements.txt puede producir resultados diferentes cuando se actualizan dependencias transitivas.

Conclusión

Python Poetry transforma la gestión de dependencias de una fuente de fricción a un flujo de trabajo ágil. Al combinar resolución de dependencias, gestión de entornos virtuales y publicación de paquetes en una sola herramienta, elimina la cadena de herramientas fragmentada que durante mucho tiempo ha frustrado a los desarrolladores de Python. El archivo pyproject.toml ofrece una única fuente de verdad, el lock file garantiza instalaciones reproducibles y el resolvedor de dependencias detecta conflictos antes de que provoquen fallos en runtime.

Tanto si estás construyendo una librería para PyPI, gestionando una aplicación compleja con docenas de dependencias, o colaborando con un equipo que necesita entornos consistentes, Poetry aporta la estructura y fiabilidad que pip por sí solo no puede ofrecer. Su curva de aprendizaje es moderada — la mayoría de desarrolladores se vuelven productivos en menos de una hora — y el tiempo ahorrado depurando dependencias se amortiza durante la primera semana.

Empieza ejecutando poetry new en tu próximo proyecto o poetry init en uno existente. Añade tus dependencias, haz commit del lock file y vive una gestión de dependencias como debería ser. Para flujos de trabajo de data science en Jupyter, combina el control de dependencias a nivel de proyecto de Poetry con RunCell (opens in a new tab) para un entorno que gestiona tanto el package management como el análisis interactivo de forma fluida.