Running tasks#

An example task#

Poe tasks are defined in your pyproject.toml file under tool.poe.tasks

The following toml example defines a task called test that consists of the associated command.

test = "pytest --cov=poethepoet"

This task can the be run via the poe cli as poe test.


If your pyproject defines pytest as a dependency with poetry, then poe will run the task with pytest from the poetry managed virtualenv, so you don’t need to explicitly activate the virtualenv via poetry shell or poetry run.

Click here for a real example.

Run a task with the poe CLI#

The prefered way to run poe is via the standalone CLI.

poe test

The above command can only be ran if you’ve installed Poe globally, or if you’ve sourced the venv that Poe the Poet is installed in (e.g. using poetry shell).

Running Poe as a Python module#

You can also run poe as a python module

python -m poethepoet [options] test [task_args]

Running Poe as a Poetry plugin#

If you’ve installed it as a poetry plugin (for poetry >= 1.2), you can run it like so

poetry self add poethepoet[poetry_plugin]
poetry poe [options] test [task_args]

Running Poe as a Poetry dependency#

If you’ve installed it as a dev dependency with poetry, you can run it like so

poetry add --group dev poethepoet
poetry run poe [options] test [task_args]


In this case you might want create an alias like alias poe='poetry run poe'.

Passing arguments#

By default additional arguments are passed to the task so

poe test -v tests/

will result in the following being run inside poetry’s virtualenv

pytest --cov=poethepoet -v tests/