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

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

Add poethepoet as a development dependency:

uv add --dev poethepoet

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 expanded syntax:

[tool.poe.tasks]
# Simple command task
test = "pytest tests/"

# Task with arguments
lint = { cmd = "ruff check ${path}", args = [
    { name = "path", default = "." }
]}

# Task with shell script (multiple commands)
setup = { shell = """
    uv sync
    pre-commit install
    """ }

Running Tasks with Poe

Execute tasks using the poe command:

# Run a simple task
uv run poe test

# Run a task with arguments
uv run poe lint src/

# Chain multiple tasks
uv run poe format lint test
ℹ️

If Poe doesn’t automatically detect your uv project, specify it explicitly in your configuration:

[tool.poe]
executor.type = "uv"
Last updated on

Please submit corrections and feedback...