Installation & Self-Management

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the Python Reference bibliography.

Poetry is an application with its own dependencies, and it must be installed so that they never mix with the dependencies of the projects it manages. This page shows the three supported ways, the poetry self commands that manage the installation afterwards, and shell completions. It was written against Poetry 2.5.1 (2026-09-20), which needs Python 3.10 or newer to run; the projects it manages may target any Python range. Every command was run on CPython 3.14.6 on 2026-10-22 with all Poetry directories pointed into a scratch directory (shown as …).

The rule: a dedicated environment

The Poetry documentation is unusually blunt: Poetry "should always be installed in a dedicated virtual environment … It should in no case be installed in the environment of the project that is to be managed by Poetry", and that environment "should not be activated for running poetry commands". If Poetry and the project share an environment, poetry install may upgrade or remove Poetry’s own dependencies (dulwich, keyring, packaging, …) in the middle of the run, with errors that are hard to trace. So:

  • never pip install poetry into a project venv, and never list poetry in a project’s dependencies;

  • never sudo pip install poetry into a system Python;

  • the three methods below each create an isolated environment for Poetry.

Source: Poetry: Installation.

With pipx

pipx installs a Python application into its own venv and puts its command on PATH. It is the method the Poetry documentation lists first:

pipx install poetry==2.5.1
creating virtual environment...
installing poetry from spec 'poetry==2.5.1'...
…
  installed package poetry 2.5.1, installed using Python 3.14.6
  These apps are now available
    - poetry
…
done! ✨ 🌟 ✨

(The left-out lines are pipx’s notes that another poetry was already on PATH on that machine and that pipx’s bin directory is not on PATH yet; pipx ensurepath fixes the latter.)

Several versions can live side by side with --suffix, which is handy for testing a project against the last 1.x release:

pipx install --suffix=@1.8.5 poetry==1.8.5
poetry@1.8.5 --version
poetry --version
creating virtual environment...
installing poetry from spec 'poetry==1.8.5'...
  installed package poetry 1.8.5 (poetry@1.8.5), installed using Python 3.14.6
  These apps are now available
    - poetry@1.8.5
…
done! ✨ 🌟 ✨
Poetry (version 1.8.5)
Poetry (version 2.5.1)

pipx upgrade poetry and pipx uninstall poetry manage it afterwards, and pipx inject poetry <plugin> adds plugins (see Plugins).

Source: Poetry: Installing with pipx.

With the official installer

The installer script at https://install.python-poetry.org (developed in its own repository) creates a venv for Poetry and a poetry wrapper outside it:

curl -sSL https://install.python-poetry.org | python3 -
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

(With a Microsoft Store Python, use python instead of py.) Downloaded to a file and run with a pinned version into a chosen location:

curl -sSL https://install.python-poetry.org -o install-poetry.py
POETRY_HOME=…/opt-poetry python3.14 install-poetry.py --version 2.5.1
Retrieving Poetry metadata

# Welcome to Poetry!

This will download and install the latest version of Poetry,
a dependency and package manager for Python.

It will add the `poetry` command to Poetry's bin directory, located at:

…/opt-poetry/bin

You can uninstall at any time by executing this script with the --uninstall option,
and these changes will be reverted.

Installing Poetry (2.5.1)
Installing Poetry (2.5.1): Creating environment
Installing Poetry (2.5.1): Installing Poetry
Installing Poetry (2.5.1): Creating script
Installing Poetry (2.5.1): Done

Poetry (2.5.1) is installed now. Great!

To get started you need Poetry's bin directory (…/opt-poetry/bin) in your `PATH`
environment variable.
…

The options, each with an environment-variable form:

Option Variable Effect

--version 2.5.1

POETRY_VERSION

Install that version instead of the latest.

-p, --preview

POETRY_PREVIEW=1

Allow pre-releases.

--git <url>

Install from a Git repository, for example https://github.com/python-poetry/poetry.git@main.

--path <path>

Install from a local file or directory.

-f, --force

Install on top of an existing version.

-y, --yes

Accept all prompts.

--uninstall

POETRY_UNINSTALL=1

Remove Poetry again.

POETRY_HOME

Where to install (default below).
Platform Poetry’s venv The poetry command

Linux/Unix

~/.local/share/pypoetry/venv

~/.local/bin/poetry

macOS

~/Library/Application Support/pypoetry/venv

~/.local/bin/poetry

Windows

%APPDATA%\pypoetry\venv

%APPDATA%\Python\Scripts\poetry

any, with POETRY_HOME

$POETRY_HOME/venv

$POETRY_HOME/bin/poetry

On some Debian and Ubuntu Pythons the installer fails with FileNotFoundError: … /pypoetry/venv/bin/python; the installer’s README gives export DEB_PYTHON_INSTALL_LAYOUT=deb as the workaround.

Source: Poetry: Installing with the official installer, install.python-poetry.org (README).

Manually, in a venv

The most transparent method is a venv that holds only Poetry:

export POETRY_HOME=/opt/poetry
python3 -m venv $POETRY_HOME
$POETRY_HOME/bin/pip install poetry==2.5.1
$POETRY_HOME/bin/poetry --version
Poetry (version 2.5.1)

This is how Poetry was installed for every example in this section, and how the Docker images on CI Caching & Containers install it.

Source: Poetry: Installing manually.

In CI

The "CI recommendations" in the installation page ask for reproducibility first: pin the version (the docs' examples still show 2.0.0), prefer pipx or the manual method, and if you use the installer script keep your own copy of it and set POETRY_HOME so the paths are predictable. The official documentation has no CI-provider guide beyond that; see CI Caching & Containers.

Source: Poetry: CI recommendations.

Updating Poetry

poetry self update            # to the latest release
poetry self update --preview  # including pre-releases
poetry self update 2.5.1      # to a given version

self update works for the installer and manual methods. The documentation warns that "especially on Windows, self update may be problematic", and recommends re-running the installer there. With pipx, use pipx upgrade poetry (or pipx install --force poetry==<version>) instead.

Source: Poetry CLI: self update.

poetry self

Poetry treats its own installation as a small non-package project. poetry self commands work on it as the normal commands work on yours:

Command Effect

poetry self add <pkg>

Add a package (normally a plugin) to Poetry’s environment. Options as for add: -e, -E, --allow-prereleases, --source, --dry-run.

poetry self remove <pkg>

Remove an added package.

poetry self install

Install the added packages from the self lock file (--dry-run; --sync is deprecated in favour of self sync).

poetry self sync

Install exactly the added packages, removing others.

poetry self lock

Lock the added packages.

poetry self show

List the packages in Poetry’s environment (--addons for the added ones only, --tree, --latest, --outdated).

poetry self show plugins

List the installed plugins.

poetry self update

Update Poetry itself.

 
poetry self add poetry-plugin-export
poetry self show plugins
Using version ^1.10.1 for poetry-plugin-export

Updating dependencies
Resolving dependencies...

Package operations: 1 install, 0 updates, 0 removals

  - Installing poetry-plugin-export (1.10.1)

Writing lock file

  - poetry-plugin-export (1.10.1) Poetry plugin to export the dependencies to various formats
      1 application plugin

      Dependencies
        - poetry (>=2.1.0,<3.0.0)
        - poetry-core (>=2.1.0,<3.0.0)
        - tomlkit (>=0.11.4,<1.0.0)

The "project" behind poetry self is a pyproject.toml and poetry.lock in Poetry’s configuration directory (here $POETRY_CONFIG_DIR). After the command above it contained:

[tool.poetry]
name = "poetry-instance"
version = "2.5.1"
description = ""
authors = []
license = ""
package-mode = false

[tool.poetry.dependencies]
python = "3.14.6"
poetry = "2.5.1"

[dependency-groups]
additional = [
    "poetry-plugin-export (>=1.10.1,<2.0.0)"
]

Poetry pins itself and the interpreter, so that self add can never change Poetry’s version. In 2.5.1, poetry self show --addons printed the whole runtime environment (46 packages, poetry-plugin-export among them) rather than only the added packages, so read self show plugins for the list of plugins.

Source: Poetry CLI: self, self add, self install, self lock, self remove, self show, self show plugins, self sync.

Shell completions

poetry completions <shell> prints a completion script for bash, fish or zsh (poetry help completions has the details):

# Bash, auto-loaded (recommended)
poetry completions bash >> ~/.bash_completion
# Bash, lazy-loaded
poetry completions bash > ${XDG_DATA_HOME:-~/.local/share}/bash-completion/completions/poetry
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish
# Zsh: then add "fpath+=~/.zfunc" and "autoload -Uz compinit && compinit" to ~/.zshrc
poetry completions zsh > ~/.zfunc/_poetry
# Oh My Zsh: then add poetry to the plugins array in ~/.zshrc
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry
# prezto
poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry

You may need to restart the shell; with prezto, delete ~/.cache/prezto/zcompcache if completions still do not appear. PowerShell is not supported: poetry completions powershell answers [shell] argument must be one of bash, zsh, fish.

Source: Poetry: Enable tab completion, Bash, auto-loaded, lazy-loaded, Fish, Zsh, Oh My Zsh, prezto.

pip and Poetry

pip comes with Python (ensurepip) and is installed into every venv; Poetry is installed once, outside all of them. The pip equivalent of this page is Installing & Upgrading pip.

References