Installation

Installing Poe the Poet

There are a few ways to install Poe the Poet depending on your preferences.

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

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.