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.35.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

Add poethepoet as a dev dependency

poetry add --group dev poethepoet

And run it

poetry run poe

With uv

Add poethepoet as a dev dependency

uv add --dev poethepoet

And run it

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.