poethepoet

What it is and what it does

Poe the Poet is a task runner designed to integrate with poetry and uv projects, though it also works standalone. You define tasks declaratively in pyproject.toml (or poe_tasks.toml) as commands, shell scripts, Python expressions, or references to Python functions. The poe CLI then executes these tasks, automatically using your project's virtualenv so you don't need to prefix commands with `poetry run` or `uv run`. Tasks can be composed into sequences, run in parallel, or organized as directed acyclic graphs. It supports named CLI arguments, environment variable references, .env file loading, and self-documenting help output.

The package is lightweight (three dependencies: pastel, pyyaml, tomli) and can be installed globally via pipx, added as a poetry plugin, or embedded as a library in other tools. It's actively maintained, supports modern Python versions (3.10–3.14), and has no known security vulnerabilities.

Use it for:

• Define and run test, lint, and format commands in a single pyproject.toml without shell scripts.
• Orchestrate multi-step CI/CD workflows as task sequences or DAGs with automatic dependency resolution.
• Replace Makefile-style task runners with a Python-native, poetry-integrated alternative.
• Compose shell commands, AWS CLI calls, or SSH tunnels with named arguments and environment variable substitution.
• Embed task execution in other Python tools or frameworks via the library API.
• Run project tasks without memorizing command syntax by using self-documenting help and shell completion.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A task runner that reads task definitions from pyproject.toml or poe_tasks.toml and executes them as commands, shell scripts, Python expressions, or function calls, with support for sequential, parallel, and DAG composition.

Yes. Poe the Poet is a well-maintained, actively developed task runner with low install friction, no security issues, and a permissive license. It's a natural fit for poetry and uv projects, and useful as a general-purpose task runner even without them. Install it if you want to centralize project automation in pyproject.toml and avoid shell scripts or Makefiles.

Install

poethepoet on PyPI

pip install poethepoet

uv add poethepoet

poetry add poethepoet

Installing poethepoet

Before you install

Low friction: pure Python wheel with only three runtime dependencies (pastel, pyyaml, tomli). Actively maintained with a release 40 days ago and 2060 GitHub stars. Supports Python 3.10 through 3.14.

License in practice

MIT license (permissive). No restrictions on use, modification, or distribution in commercial or private projects.

Quickstart

# Install globally or as a poetry plugin
pipx install poethepoet

# Add to pyproject.toml
[tool.poe.tasks]
test = "pytest --cov=my_app"

# Run task
poe test

Requires Python 3.10 or later. Works best when poetry or uv is already managing your project environment.

Verify before relying

• Whether shell completion setup is automatic or requires manual configuration per shell type.
• Performance characteristics when composing large DAGs or running many parallel tasks.
• Compatibility with non-standard virtualenv managers beyond poetry and uv.

Package facts

Evidence: poethepoet-0.48.0-py3-none-any.whl

Keywords: automation, tasks, task-runner, plugin, poetry, poe

Tags

More Libraries packages