Poetry es una herramienta para administrar dependencias, entornos virtuales, versiones y empaquetado en proyectos Python. Centraliza la configuración en pyproject.toml, genera un archivo de bloqueo reproducible y ofrece comandos para añadir, actualizar, eliminar y publicar paquetes. Su objetivo principal es que el equipo instale las mismas versiones compatibles en desarrollo, integración continua y producción.
Qué problema resuelve Poetry
Un proyecto puede comenzar con unos pocos paquetes instalados manualmente, pero pronto aparecen conflictos entre versiones, dependencias indirectas y entornos diferentes. Poetry registra restricciones declaradas y resuelve una combinación compatible. La documentación oficial de Poetry describe instalación, configuración, entornos y publicación.
Instalar Poetry
Utiliza el método recomendado por la documentación oficial para tu sistema. Después confirma:
poetry --versionNo instales Poetry dentro de cada entorno del proyecto como una dependencia normal. Es una herramienta de desarrollo que administra esos entornos.
Crear un proyecto nuevo
poetry new mi_paqueteEl comando genera una estructura básica:
mi_paquete/
├── pyproject.toml
├── README.md
├── src/
│ └── mi_paquete/
│ └── __init__.py
└── tests/
└── __init__.pyLa organización con src ayuda a evitar importar accidentalmente archivos del directorio de trabajo en lugar del paquete instalado.
Inicializar Poetry en un proyecto existente
cd proyecto_existente
poetry initEl asistente pregunta nombre, versión de Python, licencia y dependencias. También puedes aceptar los valores predeterminados y editar pyproject.toml después.
Entender pyproject.toml
Este archivo reúne metadatos y dependencias. Una configuración puede verse así:
[project]
name = "mi-aplicacion"
version = "0.1.0"
description = "Aplicación de ejemplo"
requires-python = ">=3.11,<4.0"
dependencies = [
"requests>=2.32,<3.0"
]
[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
ruff = "^0.9"El formato exacto depende de la versión y del tipo de proyecto. Evita copiar configuraciones antiguas sin revisar la documentación correspondiente.
Añadir dependencias
poetry add requestsPoetry modifica el archivo de configuración, resuelve versiones y actualiza poetry.lock. Para una dependencia de desarrollo:
poetry add --group dev pytestLos grupos permiten separar herramientas de pruebas, documentación o análisis.
Eliminar y actualizar paquetes
poetry remove requests
poetry updateupdate busca versiones nuevas dentro de las restricciones. No debe confundirse con install, que utiliza el archivo de bloqueo existente para reproducir el entorno.
Qué es poetry.lock
poetry.lock registra versiones concretas de dependencias directas e indirectas. Debe incluirse en el repositorio para aplicaciones, de modo que el equipo y la CI instalen el mismo conjunto.
Cuando una biblioteca se distribuye a otros proyectos, las restricciones del paquete siguen siendo importantes, porque el consumidor necesita resolverlas junto con sus propias dependencias.
Instalar el proyecto
poetry installPoetry crea o reutiliza un entorno virtual e instala el proyecto y sus dependencias. Si solo necesitas dependencias de producción:
poetry install --without devRevisa los grupos definidos; el nombre y las opciones deben coincidir con la configuración.
Ejecutar comandos
poetry run python -m mi_aplicacion
poetry run pytest
poetry run ruff check .poetry run ejecuta el comando dentro del entorno administrado sin necesidad de activarlo manualmente.
Activar el entorno
Las versiones modernas de Poetry pueden utilizar comandos o plugins diferentes para abrir una shell. Una opción universal es obtener la ruta del entorno:
poetry env info --pathTambién puedes trabajar siempre con poetry run, lo que reduce confusiones sobre qué intérprete está activo.
Elegir la versión de Python
poetry env use python3.12El intérprete debe cumplir requires-python. Si no se encuentra, instala la versión en el sistema o usa un gestor de versiones.
Restricciones de versiones
Poetry admite rangos, versiones exactas, operadores de compatibilidad y dependencias desde Git o rutas locales. La documentación oficial de especificación de dependencias explica cada sintaxis.
No declares rangos innecesariamente amplios ni fijes todas las dependencias directas sin motivo. El archivo de bloqueo ya aporta reproducibilidad al entorno.
Dependencias opcionales
Una biblioteca puede ofrecer funciones opcionales, por ejemplo soporte para bases de datos o imágenes. Define extras o grupos según el caso. Los extras forman parte de la interfaz para consumidores; los grupos suelen organizar el entorno del propio proyecto.
Poetry y pruebas
Añade pytest al grupo de desarrollo y ejecuta:
poetry run pytest -qLa guía de pruebas unitarias en Python ayuda a organizar los casos. Mantén las herramientas de test fuera de las dependencias de ejecución si el producto no las necesita.
Poetry en GitHub Actions
La CI debe instalar Poetry, seleccionar Python, restaurar caché si corresponde, ejecutar poetry install y después los tests. Consulta la guía de GitHub Actions para Python.
Fija una versión de Poetry en la CI para evitar que un cambio de herramienta altere el pipeline sin revisión.
Variables de entorno
Poetry gestiona paquetes, no secretos de la aplicación. Utiliza variables de entorno o un gestor de secretos. La guía para leer variables de entorno en Python explica validación y archivos .env.
Construir el paquete
poetry buildEl comando genera distribuciones en dist/. Antes de publicar, instala el paquete construido en un entorno limpio y ejecuta pruebas. Comprueba que README, licencia, metadatos y archivos necesarios estén incluidos.
Publicar
Poetry puede configurar repositorios y tokens para publicar. Nunca escribas credenciales dentro del proyecto. Prueba primero en un índice de prueba cuando el paquete sea nuevo. La versión debe actualizarse antes de generar una nueva distribución.
Docker
En contenedores, una estrategia es exportar o instalar dependencias durante la construcción. Evita crear entornos virtuales innecesarios dentro del contenedor si la imagen ya es el entorno aislado. También utiliza capas de forma que el caché de dependencias no se invalide con cada cambio de código.
Poetry frente a pip y venv
pip instala paquetes y venv crea entornos. Poetry añade resolución, bloqueo, grupos, construcción y publicación en una interfaz integrada. Para scripts pequeños, pip y venv pueden ser suficientes. Para proyectos colaborativos o paquetes, Poetry aporta consistencia.
La guía sobre instalación de bibliotecas con pip ayuda a comparar el flujo tradicional.
Errores frecuentes
Los problemas comunes son olvidar confirmar poetry.lock, ejecutar Python fuera del entorno, mezclar cambios manuales y comandos sin regenerar el lock, declarar una versión de Python incompatible y usar opciones de tutoriales antiguos.
Buenas prácticas
Define una versión de Python clara, separa dependencias de desarrollo, revisa cambios del lock en pull requests, ejecuta tests después de actualizar y documenta los comandos del proyecto. El archivo de bloqueo no sustituye las actualizaciones de seguridad; programa revisiones periódicas.
Poetry resulta más valioso cuando todo el equipo sigue el mismo flujo. Con configuración, lock y comandos reproducibles, instalar un proyecto deja de depender de instrucciones manuales y se convierte en un proceso verificable.
