{"id":2194,"library":"poethepoet","title":"Poe the Poet","description":"Poe the Poet is a modern and flexible task runner designed to integrate seamlessly with `poetry` and `uv` projects. It allows defining and running project-specific commands, scripts, and more complex workflows via `pyproject.toml`. As of version 0.44.0, it maintains an active development pace with frequent minor releases addressing new features, bug fixes, and occasional breaking changes.","status":"active","version":"0.44.0","language":"en","source_language":"en","source_url":"https://github.com/nat-n/poethepoet","tags":["task runner","poetry","uv","cli","build automation"],"install":[{"cmd":"pip install poethepoet","lang":"bash","label":"Install Poe the Poet"}],"dependencies":[],"imports":[{"note":"While primarily a CLI tool, Poe can be interacted with programmatically through its main application class.","symbol":"PoeThePoet","correct":"from poethepoet.app.app import PoeThePoet"}],"quickstart":{"code":"# pyproject.toml\n# ...\n[tool.poe.tasks]\nhello = \"echo Hello from Poe!\"\nlint = { cmd = \"ruff check .\", help = \"Run ruff linter\" }\ntest = \"pytest\"\n\n# Terminal execution (from project root):\n# poe hello\n# poe lint\n# poe test","lang":"python","description":"Poe tasks are defined in your project's `pyproject.toml` file under `[tool.poe.tasks]`. Each task is a key-value pair, where the key is the task name and the value can be a simple command string or a dictionary for more complex configurations (e.g., adding help text). Tasks are executed via the `poe <task_name>` command in your terminal."},"warnings":[{"fix":"Review existing projects with nested 'include' statements (e.g., `include = ['path/to/another.toml']`) for unintended task or environment variable conflicts.","message":"Transitive includes are now loaded by default from v0.44.0. Previously, nested 'include' entries were silently ignored. This change may cause previously ignored config files to be loaded, potentially introducing new tasks or environment variables.","severity":"breaking","affected_versions":">=0.44.0"},{"fix":"Consult the v0.43.0 release notes and documentation on task variables, boolean arguments, and private variables to adjust existing task definitions.","message":"Task variable management was refactored in v0.43.0. Boolean argument semantics were improved, and private variables introduced. This might change how environment variables are set or interpreted, especially for boolean flags passed to tasks.","severity":"breaking","affected_versions":">=0.43.0"},{"fix":"Follow the instructions in the official documentation to reinstall your shell's completion script after upgrading `poethepoet`.","message":"Shell completion scripts must be reinstalled after certain updates (e.g., v0.41.0, v0.42.0, v0.42.1). New completion features or fixes won't apply until the script is updated for your specific shell environment.","severity":"gotcha","affected_versions":">=0.41.0"},{"fix":"Upgrade your project's Python interpreter to 3.10 or newer, or pin `poethepoet` to a version `<0.38.0`.","message":"Support for Python 3.9 was dropped in v0.38.0. Projects using `poethepoet` on Python 3.9 will fail to install or run this version.","severity":"breaking","affected_versions":">=0.38.0"},{"fix":"Ensure `poethepoet` is installed and activated within your project's virtual environment, or carefully manage your system's PATH to prioritize the desired `poe` command.","message":"The `poe` CLI command can conflict if you have `poetry` also installed and its `poe` alias/shim is present in your PATH. This can lead to unexpected command execution.","severity":"gotcha","affected_versions":"all"},{"fix":"Use `cmd` for simple, atomic commands and `shell` when shell-specific syntax or features (e.g., `|`, `>`, `&&`) are required. If unsure, `shell` is often the more flexible default, but `cmd` can be more direct and portable.","message":"Understand the difference between `cmd` and `shell` task types. `cmd` executes directly without an intermediary shell, while `shell` executes via the system shell, allowing shell features like pipes, redirects, and environment variable expansion.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}