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.

[tool.poe.tasks]
test = "pytest --cov=poethepoet"

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

Hint

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 preferred 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]

Hint

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/favorite_test.py

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

pytest --cov=poethepoet -v tests/favorite_test.py