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

[Poe the Poet](https://poethepoet.natn.io) provides a flexible task runner that works seamlessly with [uv](https://pydevtools.com/handbook/reference/uv.md) projects. This guide shows how to set up and use Poe for running common development tasks.

## Prerequisites

- [uv](https://pydevtools.com/handbook/reference/uv.md) installed on your system
- A Python project with a `pyproject.toml` file

## Installing Poe

Install poethepoet as a global tool:

```console
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:

```console
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`:

```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:

```toml
[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:

```console
# 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`:

```console
uv run poe test
```

## Learn more

- [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.