Introduction #

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.

System requirements #

Poetry requires Python 3.8+. It is multi-platform and the goal is to make it work equally well on Linux, macOS and Windows.

Installation #

If you are viewing documentation for the development branch, you may wish to install a preview or development version of Poetry. See the advanced installation instructions to use a preview or alternate version of Poetry.

We provide a custom installer that will install Poetry in a new virtual environment to isolate it from the rest of your system. This ensures that dependencies will not be accidentally upgraded or uninstalled, and allows Poetry to manage its own environment.

  1. Install Poetry

    The installer script is available directly at, and is developed in its own repository. The script can be executed directly (i.e. ‘curl python’) or downloaded and then executed from disk (e.g. in a CI environment).

    The installer has been deprecated and removed from the Poetry repository. Please migrate from the in-tree version to the standalone version described above.

    Linux, macOS, Windows (WSL)

    curl -sSL | python3 -
    Note: On some systems, python may still refer to Python 2 instead of Python 3. We always suggest the python3 binary to avoid ambiguity.

    Windows (Powershell)

    (Invoke-WebRequest -Uri -UseBasicParsing).Content | py -
    If you have installed Python through the Microsoft Store, replace py with python in the command above.
  2. Install Poetry (advanced)

    By default, Poetry is installed into a platform and user-specific directory:

    • ~/Library/Application Support/pypoetry on MacOS.
    • ~/.local/share/pypoetry on Linux/Unix.
    • %APPDATA%\pypoetry on Windows.

    If you wish to change this, you may define the $POETRY_HOME environment variable:

    curl -sSL | POETRY_HOME=/etc/poetry python3 -

    If you want to install prerelease versions, you can do so by passing the --preview option to the installation script or by using the $POETRY_PREVIEW environment variable:

    curl -sSL | python3 - --preview
    curl -sSL | POETRY_PREVIEW=1 python3 -

    Similarly, if you want to install a specific version, you can use --version option or the $POETRY_VERSION environment variable:

    curl -sSL | python3 - --version 1.2.0
    curl -sSL | POETRY_VERSION=1.2.0 python3 -

    You can also install Poetry from a git repository by using the --git option:

    curl -sSL | python3 - --git
  3. Add Poetry to your PATH

    The installer creates a poetry wrapper in a well-known, platform-specific directory:

    • $HOME/.local/bin on Unix.
    • %APPDATA%\Python\Scripts on Windows.
    • $POETRY_HOME/bin if $POETRY_HOME is set.

    If this directory is not present in your $PATH, you can add it in order to invoke Poetry as poetry.

    Alternatively, the full path to the poetry binary can always be used:

    • ~/Library/Application Support/pypoetry/venv/bin/poetry on MacOS.
    • ~/.local/share/pypoetry/venv/bin/poetry on Linux/Unix.
    • %APPDATA%\pypoetry\venv\Scripts\poetry on Windows.
    • $POETRY_HOME/venv/bin/poetry if $POETRY_HOME is set.
  4. Use Poetry

    Once Poetry is installed and in your $PATH, you can execute the following:

    poetry --version

    If you see something like Poetry (version 1.2.0), your install is ready to use!

  5. Update Poetry

    Poetry is able to update itself when installed using the official installer.

    poetry self update

    If you want to install pre-release versions, you can use the --preview option.

    poetry self update --preview

    And finally, if you want to install a specific version, you can pass it as an argument to self update.

    poetry self update 1.2.0
    Poetry 1.1 series releases are not able to update in-place to 1.2 or newer series releases. To migrate to newer releases, uninstall using your original install method, and then reinstall using the methods above.
  6. Uninstall Poetry

    If you decide Poetry isn’t your thing, you can completely remove it from your system by running the installer again with the --uninstall option or by setting the POETRY_UNINSTALL environment variable before executing the installer.

    curl -sSL | python3 - --uninstall
    curl -sSL | POETRY_UNINSTALL=1 python3 -

    If you installed using the deprecated script, you should remove the path it uses manually, e.g.

    rm -rf "${POETRY_HOME:-~/.poetry}"

    Also remove ~/.poetry/bin from your $PATH in your shell configuration, if it is present.

Enable tab completion for Bash, Fish, or Zsh #

poetry supports generating completion scripts for Bash, Fish, and Zsh. See poetry help completions for full details, but the gist is as simple as using one of the following:

Bash #

poetry completions bash >> ~/.bash_completion

Lazy-loaded #

poetry completions bash > ${XDG_DATA_HOME:-~/.local/share}/bash-completion/completions/poetry

Fish #

poetry completions fish > ~/.config/fish/completions/

Zsh #

poetry completions zsh > ~/.zfunc/_poetry

You must then add the following lines in your ~/.zshrc, if they do not already exist:

autoload -Uz compinit && compinit

Oh My Zsh #

mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry

You must then add poetry to your plugins array in ~/.zshrc:


prezto #

poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry
You may need to restart your shell in order for these changes to take effect.