Poe the Poet

0.44.0 · active · verified Thu Apr 09

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.

Warnings

breaking 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.
Fix: Review existing projects with nested 'include' statements (e.g., `include = ['path/to/another.toml']`) for unintended task or environment variable conflicts.
breaking 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.
Fix: Consult the v0.43.0 release notes and documentation on task variables, boolean arguments, and private variables to adjust existing task definitions.
gotcha 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.
Fix: Follow the instructions in the official documentation to reinstall your shell's completion script after upgrading `poethepoet`.
breaking 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.
Fix: Upgrade your project's Python interpreter to 3.10 or newer, or pin `poethepoet` to a version `<0.38.0`.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install poethepoet Install Poe the Poet

Imports

PoeThePoet
```
from poethepoet.app.app import PoeThePoet
```
While primarily a CLI tool, Poe can be interacted with programmatically through its main application class.

Quickstart

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.

# pyproject.toml
# ...
[tool.poe.tasks]
hello = "echo Hello from Poe!"
lint = { cmd = "ruff check .", help = "Run ruff linter" }
test = "pytest"

# Terminal execution (from project root):
# poe hello
# poe lint
# poe test

view raw JSON →