Poe the Poet Documentation#
Poe the Poet is a batteries included task runner that works well with poetry.
It provides a simple way to define project tasks within your pyproject.toml, and either a standalone CLI or a poetry plugin to run them using your project’s virtual environment.
“Simple things should be simple, complex things should be possible.” – Alan Kay
✅ Straight forward declaration of project tasks in your pyproject.toml
✅ Tasks are run in poetry’s virtualenv (or another env you specify)
✅ Shell completion of task names (and global options too for zsh)
✅ The poe CLI can be used standalone, or as a plugin for poetry
✅ Concise commands with extra arguments passed to the task
poe [options] task [task_args]
✅ Easily define CLI arguments for your tasks
✅ Tasks can specify and reference environment variables, even without a shell
✅ Tasks are self documenting, with optional help messages (just run
poe with no arguments)
✅ Works with .env files
✅ Can be used as a library to embed in other tools
pipx install poethepoet
Add a section for poe tasks to your pyproject.toml
[tool.poe.tasks] test = "pytest --cov=my_app" # a simple command task serve.script = "my_app.service:run(debug=True)" # python script based task tunnel.shell = "ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD &" # (posix) shell based task
Run one of your tasks using the CLI
poe test -v
The extra argument is appended to the task command.
If you’re using poetry, then poe will automatically use the poetry managed virtualenv to find executables and python libraries, without needing to use
poetry run or
Usage without poetry#
Poe the Poet was originally intended as the missing task runner for poetry. But it works just as well with any other kind of virtualenv, or simply as a general purpose way to define handy tasks for use within a certain directory structure! This behaviour is configurable via the tool.poe.executor global option.
By default poe will run tasks in the poetry managed virtual environment, if the pyproject.toml contains a
tool.poetry section. If it doesn’t then poe looks for a virtualenv to use at
./venv relative to the pyproject.toml.
If no virtualenv is found then poe will run tasks without any special environment management.
Run poe from anywhere#
By default poe will detect when you’re inside a project with a pyproject.toml in the root. However if you want to run it from elsewhere then that is supported by using the
--root option to specify an alternate location for the toml file. The task will run with the given location as the current working directory.
In all cases the path to project root (where the pyproject.toml resides) will be available as
$POE_ROOT within the command line and process. The variable
$POE_PWD contains the original working directory from which poe was run.