Introduction

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.10+. It is multi-platform and the goal is to make it work equally well on Linux, macOS and Windows.

Installation #

Note

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.

pipx is used to install Python CLI applications globally while still isolating them in virtual environments. pipx will manage upgrades and uninstalls when used to install Poetry.

Install pipx

If pipx is not already installed, you can follow any of the options in the official pipx installation instructions. Any non-ancient version of pipx will do.
Install Poetry
```
pipx install poetry
```
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, having multiple versions installed at the same time etc.

pipx can install different versions of Poetry, using the same syntax as pip:
```
pipx install poetry==1.8.4
```
pipx can also install versions of Poetry in parallel, which allows for easy testing of alternate or prerelease versions. Each version is given a unique, user-specified suffix, which will be used to create a unique binary name:
```
pipx install --suffix=@1.8.4 poetry==1.8.4
[email protected] --version
```
```
pipx install --suffix=@preview --pip-args=--pre poetry
poetry@preview --version
```
Finally, pipx can install any valid pip requirement spec, which allows for installations of the development version from git, or even for local testing of pull requests:
```
pipx install --suffix @main git+https://github.com/python-poetry/poetry.git@main
pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head
```
Update Poetry
```
pipx upgrade poetry
```
Uninstall Poetry
```
pipx uninstall poetry
```

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

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)