How to Use Poe the Poet as a Task Runner with uv

Poe the Poet provides a flexible task runner that works seamlessly with uv projects. This guide shows how to set up and use Poe for running common development tasks.

Prerequisites

• uv installed on your system
• A Python project with a pyproject.toml file

Installing Poe

Install poethepoet as a global tool:

uv tool install poethepoet

This gives you a poe command available everywhere, with shell completions and shorter commands (no uv run prefix needed). Poe automatically detects and works with different project types, including uv, Poetry, and plain virtualenv projects.

Alternatively, you can add it as a project-level dev dependency:

uv add --dev poethepoet

With a project-level install, you’ll need to prefix commands with uv run (e.g., uv run poe test).

Defining Tasks in pyproject.toml

Add a [tool.poe.tasks] section to your pyproject.toml:

[tool.poe.tasks]
test = "pytest tests/"
lint = "ruff check ."
format = "ruff format ."
build = "uv build"
docs = "mkdocs serve"

For more complex tasks, use table syntax for clarity and extensibility:

[tool.poe.tasks.lint]
help = "Run linter on the codebase"
cmd = "ruff check ${path}"
args = [
  { name = "path", default = "." }
]

[tool.poe.tasks.setup]
help = "Set up the development environment"
shell = """
    uv sync
    pre-commit install
"""

Running Tasks with Poe

Execute tasks using the poe command:

# Run a simple task
poe test

# Run a task with arguments
poe lint src/

# Chain multiple tasks
poe format lint test

If you installed poethepoet as a project dependency instead of globally, prefix with uv run:

uv run poe test