---
id: poethepoet
version: "0.48.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# poethepoet — A task runner that works well with poetry and uv.

License: permissive · Maintenance: active · Downloads: 6.2M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

task runner for poetry projects, pyproject.toml task automation, CLI task orchestration, poetry plugin task runner, shell command task composition, python task automation tool, project task management, task-automation, poetry-plugin, cli-tool

[View on SkillFed](https://skillfed.io/packages/poethepoet) · [View on PyPI](https://pypi.org/project/poethepoet/)