We provide a custom installer that will install Poetry in a new virtual environment and allows Poetry to manage its own environment.

1. Install Poetry

   The installer script is available directly at install.python-poetry.org, 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).

   Linux, macOS, Windows (WSL)

   curl -sSL https://install.python-poetry.org | python3 -
   

   Windows (Powershell)

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

   Note

   If you have installed Python through the Microsoft Store, replace py with python in the command above.

2. Install Poetry (advanced)

   Note

   You can skip this step, if you simply want the latest version and already installed Poetry as described in the previous step. This step details advanced usages of this installation method. For example, installing Poetry from source, using a pre-release build, configuring a different installation location etc.

   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 https://install.python-poetry.org | 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 https://install.python-poetry.org | python3 - --preview
   curl -sSL https://install.python-poetry.org | 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 https://install.python-poetry.org | python3 - --version 1.8.4
   curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.8.4 python3 -
   

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

   curl -sSL https://install.python-poetry.org | python3 - --git https://github.com/python-poetry/poetry.git@main
   

   If you want to install different versions of Poetry in parallel, a good approach is the installation with pipx and suffix.

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 2.0.0), your installation is ready to use!

5. Update Poetry

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

   Warning

   Especially on Windows, self update may be problematic so that a re-install with the installer should be preferred.

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

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 https://install.python-poetry.org | python3 - --uninstall
   curl -sSL https://install.python-poetry.org | POETRY_UNINSTALL=1 python3 -
   

Poetry can be installed manually using pip and the venv module. By doing so you will essentially perform the steps carried out by the official installer. As this is an advanced installation method, these instructions are Unix-only and omit specific examples such as installing from git.

The variable $VENV_PATH will be used to indicate the path at which the virtual environment was created.

python3 -m venv $VENV_PATH
$VENV_PATH/bin/pip install -U pip setuptools
$VENV_PATH/bin/pip install poetry

Poetry will be available at $VENV_PATH/bin/poetry and can be invoked directly or symlinked elsewhere.

To uninstall Poetry, simply delete the entire $VENV_PATH directory.

Unlike development environments, where making use of the latest tools is desirable, in a CI environment reproducibility should be made the priority. Here are some suggestions for installing Poetry in such an environment.

Version pinning

Whatever method you use, it is highly recommended to explicitly control the version of Poetry used, so that you are able to upgrade after performing your own validation. Each install method has a different syntax for setting the version that is used in the following examples.

Using pipx

Just as pipx is a powerful tool for development use, it is equally useful in a CI environment and should be one of your top choices for use of Poetry in CI.

pipx install poetry==2.0.0

Using install.python-poetry.org

Downloading a copy of the installer script to a place accessible by your CI pipelines (or maintaining a copy of the repository) is strongly suggested, to ensure your pipeline’s stability and to maintain control over what code is executed.

By default, the installer will install to a user-specific directory. In more complex pipelines that may make accessing Poetry difficult (especially in cases like multi-stage container builds). It is highly suggested to make use of $POETRY_HOME when using the official installer in CI, as that way the exact paths can be controlled.

export POETRY_HOME=/opt/poetry
python3 install-poetry.py --version 2.0.0
$POETRY_HOME/bin/poetry --version

Using pip (aka manually)

For maximum control in your CI environment, installation with pip is fully supported and something you should consider. While this requires more explicit commands and knowledge of Python packaging from you, it in return offers the best debugging experience, and leaves you subject to the fewest external tools.

export POETRY_HOME=/opt/poetry
python3 -m venv $POETRY_HOME
$POETRY_HOME/bin/pip install poetry==2.0.0
$POETRY_HOME/bin/poetry --version