Poetry es una herramienta de gestión de dependencias y empaquetado en Python que facilita el desarrollo, la instalación de librerías, la creación de entornos virtuales y la publicación de paquetes. A diferencia de pip y virtualenv, Poetry unifica el manejo de entornos y dependencias en un solo comando, con un archivo central llamado pyproject.toml.
Web oficial: https://python-poetry.org/
✅ ¿Qué es Poetry?
Poetry es una herramienta moderna para:
- Crear proyectos Python.
- Gestionar dependencias.
- Mantener versiones coherentes.
- Crear entornos virtuales automáticos.
- Publicar paquetes en PyPI.
Instalación de Poetry
Recomendado: instalar con «pipx»
💡 macOS (Homebrew)
Nota para macOS: Debido a restricciones recientes (PEP 668), la forma recomendada es instalar pipx con Homebrew para evitar errores como externally-managed-environment.
🔎 ¿Qué son brew y pipx?
- Homebrew (brew): es el gestor de paquetes más popular en macOS. Permite instalar fácilmente herramientas, librerías y utilidades desde la terminal sin tener que compilar o configurar nada manualmente. Si quieres más info y saber como instalarlo deja un comentario o házmelo saber y crearé un post sobre ello.
- pipx: es una herramienta que permite instalar y ejecutar aplicaciones Python aisladas globalmente, sin interferir con tu instalación principal de Python. Ideal para herramientas como poetry, black, httpie, etc. Ahora veremos como instalarlo.
Instalando pipx y agregando path
brew install pipx
pipx ensurepathReinicia la terminal o ejecuta este comando:
source ~/.zshrcPara instalar Poetry:
pipx install poetry🐳 Linux
Instalando pipx, agregando path y instalado Poetry
python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install poetry🪦 Windows (PowerShell)
Instalando pipx, agregando path y instalado Poetry
python -m pip install --user pipx
python -m pipx ensurepath
pipx install poetryPara verifica que todo esté correcto:
poetry --versionComandos más útiles
| Comando | Descripción |
|---|---|
| poetry new nombre_proyecto | Crea un nuevo proyecto |
| poetry init | Inicializa un proyecto en un directorio existente |
| poetry install | Instala dependencias desde pyproject.toml |
| poetry add paquete | Añade una dependencia |
| poetry remove paquete | Elimina una dependencia |
| poetry update | Actualiza todas las dependencias |
| poetry update paquete | Actualiza solo un paquete |
| poetry lock | Actualiza el archivo poetry.lock |
| poetry shell | Entra al entorno virtual |
| poetry run comando | Ejecuta un comando dentro del entorno virtual |
| poetry export | Exporta las dependencias a requirements.txt |
⚠️ A partir de Poetry 1.8, poetry shell ya no está disponible por defecto. Es necesario instalar el plugin plugin-shell si deseas seguir utilizando este comando para acceder al entorno virtual:
poetry self add poetry-plugin-shell📁 Crear Proyecto
Accederemos a la carpeta donde queremos crear el proyecto y ejecutamos:
poetry initPoetry te hará una serie de preguntas sobre el nombre, versión, autor, licencia, Python requerido, y dependencias.
Al finalizar la instalacion nos habrá creado 2 archivos:project.toml y pypoetry.lock (si hemos instalado dependencias)
project.toml:
- Es el archivo principal de configuración del proyecto. Contiene:
• Nombre, versión y descripción del proyecto.
• Autor y licencia.
• Versión mínima de Python requerida.
• Dependencias ([tool.poetry.dependencies])
• Dependencias de desarrollo ([tool.poetry.dev-dependencies])
• Configuraciones de publicación y scripts.
poetry.lock:
- Este archivo se genera automáticamente tras instalar dependencias. Sirve para:
• Fijar versiones exactas de todas las dependencias (incluidas subdependencias).
• Garantizar que todos los desarrolladores usen las mismas versiones (ideal para equipos y CI/CD).
• Evitar que una actualización automática rompa tu proyecto.
📌 Consejo:
- Puedes editar project.tom manualmente o dejar que poetry lo modifique por ti con poetry add, poetry remove, etc.
- No edites poetry.lock a mano. Déjalo siempre bajo control de Poetry.
💡 Ambos archivos deben incluirse en control de versiones (Git) para garantizar reproducibilidad.
Inicialización rápida:
poetry init --no-interactionEjemplos comunes para la pregunta de licencia y versión
Licencia:
| Entrada | Descripción |
|---|---|
| MIT | Muy permisiva. Puedes usar, copiar, modificar y distribuir con pocos requisitos. |
| Apache-2.0 | Similar a MIT, pero con protección de patentes. |
| GPL-3.0 | Licencia copyleft. Los derivados deben también ser código abierto. |
| BSD-3-Clause | Permisiva, usada en entornos académicos y empresas. |
| Proprietary | Para proyectos cerrados con derechos reservados. |
| (vacío) | No defines licencia, por tanto legalmente nadie podrá usar tu proyecto. |
Versiones compatibles de Python:
| Entrada | Significado |
|---|---|
| ^3.9 | Compatible con 3.9.x, 3.10.x, 3.11.x, etc., pero no con 4.0 |
| >=3.9 | Requiere al menos Python 3.9 (puede ser compatible con 4.0 en adelante) |
| >=3.9,<3.12 | Compatible desde 3.9 hasta (pero sin incluir) 3.12 |
| ~3.10 | Solo versiones 3.10.x |
| ==3.10.* | Igual: exactamente versiones 3.10.x |
| >=3.10,!=3.11.0 | Desde 3.10, excluyendo la versión 3.11.0 |
| >=3.9,<4.0 | Muy común: desde Python 3.9 hasta justo antes de Python 4.0 |
Añadir, actualizar, eliminar dependencias
➕ Añadir un paquete
poetry add requests🔄 Actualizar un paquete específico
poetry update requests🔄 Actualizar todo
poetry update🔄 En caso de tener las dependencias en el archivo toml podemos instalarlo todo a la vez
poetry install➖ Eliminar un paquete
poetry remove requestsCreación y uso del entorno virtual
El entorno virtual se crea cuando instalas una dependencia por primera vez, ya sea con:
poetry add paquete | poetry install o bien al introducirlas cuando hacemos el init(si ya hay dependencias definidas en el archivo pyproject.toml), Poetry crea automáticamente un entorno virtual aislado para tu proyecto.
Puedes trabajar dentro de ese entorno virtual de dos formas:
- Entrar en el entorno interactivo: (recuerda que hay que instalar su plugin como hemos visto más arriba)
poetry shellUna vez dentro, puedes ejecutar scripts normalmente con:
python3 main.py- Ejecutar comandos directamente sin activar el entorno:
poetry run python3 main.pyEsto es útil en entornos automatizados o si prefieres no cambiar de shell.
📂 Ubicación de los entornos virtuales
Poetry guarda los entornos virtuales en distintas rutas según el sistema operativo:
- macOS / Linux:/Users/<usuario>/Library/Caches/pypoetry/virtualenvs/
- Windows:%APPDATA%\pypoetry\virtualenvs\
Puedes listar todos los entornos detectados con:
poetry env listY eliminar uno con:
poetry env remove pythonSi algún entorno no aparece en la lista, pero sabes que ya no se usa, puedes eliminar la carpeta manualmente desde la ruta correspondiente.
Exportar dependencias
Para compartir el proyecto con pip, puedes generar un archivo requirements.txt:
poetry export -f requirements.txt --output requirements.txt --without-hashesAgrega –dev si quieres incluir dependencias de desarrollo.
Importar desde requirements.txt
Si ya tienes un archivo requirements.txt, puedes convertirlo fácilmente a dependencias en Poetry.
Opción rápida (línea de comandos)
poetry add $(cat requirements.txt)⚠️ Este método puede fallar si el archivo contiene comentarios (#) o líneas vacías. Para evitar errores:
grep -vE '^\s*#|^\s*$' requirements.txt > clean-req.txt
poetry add $(cat clean-req.txt)Opción alternativa con plugin oficial
Puedes usar el plugin poetry-plugin-import:
poetry self add poetry-plugin-import
poetry import requirements.txtEsto añadirá las dependencias al pyproject.toml de forma segura y limpia.
Con esta guía ya puedes empezar a trabajar con proyectos Python usando Poetry!
Espero que os sirva de ayuda.
Salu2.
