https://github.com/nat-n/poethepoet
A task runner that works well with poetry or uv.
https://github.com/nat-n/poethepoet
developer-tools development-workflow poetry poetry-plugin python task-runner uv
Last synced: 2 days ago
JSON representation
A task runner that works well with poetry or uv.
- Host: GitHub
- URL: https://github.com/nat-n/poethepoet
- Owner: nat-n
- License: mit
- Created: 2020-05-28T21:56:22.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-04-23T06:55:06.000Z (3 days ago)
- Last Synced: 2025-04-23T20:57:15.853Z (2 days ago)
- Topics: developer-tools, development-workflow, poetry, poetry-plugin, python, task-runner, uv
- Language: Python
- Homepage: https://poethepoet.natn.io/
- Size: 7.49 MB
- Stars: 1,631
- Watchers: 10
- Forks: 67
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.rst
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-github-repos - nat-n/poethepoet - A task runner that works well with poetry or uv. (Python)
- awesome-pyproject - Poe the Poet - A task runner that works well with Poetry. (Other Tools)
- awesome-starred - nat-n/poethepoet - A task runner that works well with poetry. (python)
README
# Poe the Poet
[](https://pypi.org/project/poethepoet/)
[](https://pypi.org/project/poethepoet/)
[](https://pypistats.org/packages/poethepoet)
[](https://github.com/nat-n/poethepoet/blob/doc/init-sphinx/LICENSE)**A batteries included task runner that works well with [poetry](https://python-poetry.org/) or [uv](https://docs.astral.sh/uv/).**
**[📖 Read the documentation 📖](https://poethepoet.natn.io/)**
## Features
- ✅ Straight forward [declaration of project tasks in your pyproject.toml](https://poethepoet.natn.io/tasks/index.html) (or [poe_tasks.toml](https://poethepoet.natn.io/guides/without_poetry.html#usage-without-pyproject-toml))
- ✅ Tasks are run in poetry or uv's virtualenv ([or another env](https://poethepoet.natn.io/index.html#usage-without-poetry) you specify)
- ✅ [Shell completion of task names](https://poethepoet.natn.io/installation.html#shell-completion) (and global options too for zsh)
- ✅ The poe CLI can be used standalone, or as a [plugin for poetry](https://poethepoet.natn.io/poetry_plugin.html)
- ✅ Tasks can be [commands](https://poethepoet.natn.io/tasks/task_types/cmd.html), [shell scripts](https://poethepoet.natn.io/tasks/task_types/shell.html), [python expressions](https://poethepoet.natn.io/tasks/task_types/expr.html), or references to [python functions](https://poethepoet.natn.io/tasks/task_types/script.html)
- ✅ Concise commands with extra arguments passed to the task `poe [options] task [task_args]`
- ✅ Easily [declare named CLI arguments](https://poethepoet.natn.io/guides/args_guide.html) for your tasks
- ✅ Tasks can specify and [reference environment variables](https://poethepoet.natn.io/tasks/task_types/cmd.html#ref-env-vars), even without a shell
- ✅ Tasks are [self documenting](https://poethepoet.natn.io/guides/help_guide.html), with optional help messages (just run `poe` with no arguments)
- ✅ Tasks can be composed into [sequences](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-into-sequences) or [DAGs](https://poethepoet.natn.io/guides/composition_guide.html#composing-tasks-into-graphs)
- ✅ Works with [`.env` files](https://poethepoet.natn.io/tasks/options.html#loading-environment-variables-from-an-env-file)
- ✅ Can be [used as a library](https://poethepoet.natn.io/guides/library_guide.html) to embed in other tools
- ✅ Tasks can be [defined in python packages](https://poethepoet.natn.io/guides/packaged_tasks.html) for ease of reuse across projects
- ✅ Also works fine as a [general purpose task runner](https://poethepoet.natn.io/guides/without_poetry.html)
## Quick start
1. Install the Poe the Poet via [pipx](https://pypa.github.io/pipx/) or [another method](https://poethepoet.natn.io/installation.html).
```sh
pipx install poethepoet
```2. Define some tasks in your **pyproject.toml**
```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
```3. Run your tasks via the CLI
```sh
$ poe test -v tests/unit # extra CLI arguments are appended to the underlying command
Poe => pytest --cov=my_app
...
```If you're using poetry or uv, then poe will automatically use CLI tools and libraries from your project's virtualenv without you having to run `poetry run` / `uv run`
Poe can also be [used as a general purpose task runner](https://poethepoet.natn.io/guides/without_poetry.html).
## Contributing
There's plenty to do, come say hi in the [discussions](https://github.com/nat-n/poethepoet/discussions) or [open an issue](https://github.com/nat-n/poethepoet/issues)! 👋
Also check out the [CONTRIBUTING guide](https://github.com/nat-n/poethepoet/blob/main/.github/CONTRIBUTING.rst) 🤓
## License
[MIT](https://github.com/nat-n/poethepoet/blob/main/LICENSE)
