Installation¶
Installing Poe the Poet¶
There are a few ways to install Poe the Poet depending on your preferences.
1. Install the CLI globally (recommended)¶
The following methods will make the poe
executable available anywhere on your system.
With pipx¶
pipx install poethepoet
With uv¶
uv tool install poethepoet
With homebrew¶
brew tap nat-n/poethepoet
brew install nat-n/poethepoet/poethepoet
See the homebrew formula.
With pip¶
Of course you can also install it with pip – assuming your current python environment is global.
pip install poethepoet
2. Install poethepoet as a poetry plugin¶
You can install the poethepoet poetry plugin globally like so:
poetry self add 'poethepoet[poetry_plugin]'
Or add it to poetry on a per project basis by adding the following to your pyproject.toml:
[tool.poetry.requires-plugins]
poethepoet = { version = "~0.34.0", extras = ["poetry_plugin"]}
See the poetry docs for more installation options, or see the poetry plugin docs for more details about this option.
3. Install poethepoet into your project¶
With poetry¶
poetry add --group dev poethepoet
poetry run poe
With uv¶
uv add --dev poethepoet
uv run poe
Tip
If you prefer not to install the poe CLI globally, then you can still benefit from shell completions if you create an appropriate alias in your shell, such as one of:
alias poe="poetry run poe"
alias poe="poetry poe"
alias poe="uv run poe"
Enable tab completion for your shell¶
Poe comes with tab completion scripts for bash, zsh, and fish to save you keystrokes. How to install them will depend on your shell setup.
Zsh¶
# oh-my-zsh
mkdir -p ~/.oh-my-zsh/completions
poe _zsh_completion > ~/.oh-my-zsh/completions/_poe
# without oh-my-zsh
mkdir -p ~/.zfunc/
poe _zsh_completion > ~/.zfunc/_poe
Tip
You’ll need to start a new shell for the new completion script to be loaded. If it still doesn’t work try adding a call to compinit
to the end of your zshrc file.
Bash¶
# System bash
poe _bash_completion > /etc/bash_completion.d/poe.bash-completion
# Homebrew bash
poe _bash_completion > $(brew --prefix)/etc/bash_completion.d/poe.bash-completion
How to ensure installed bash completions are enabled may vary depending on your system.
Fish¶
# Fish
poe _fish_completion > ~/.config/fish/completions/poe.fish
# Homebrew fish
poe _fish_completion > (brew --prefix)/share/fish/vendor_completions.d/poe.fish
Supported python versions¶
Poe the Poet officially supports python >=3.9, and is tested with python 3.9 to 3.13 on macOS, linux and windows.