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.

System requirements #

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

Installation #

Poetry provides a custom installer that will install poetry isolated from the rest of your system.

Install Poetry

Install Poetry by downloading and executing the installation script.

Linux, macOS, Windows (WSL)
```
curl -sSL https://install.python-poetry.org | python3 -
```
Note

Note: On some systems, python may still refer to Python 2 instead of Python 3. Please always use the python3 binary to ensure the right major version of Python is used.

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.

Note

Note that the installer does not support Python < 3.7.

Warning

The previous get-poetry.py and install-poetry.py installers are now deprecated. If you are currently using them you should migrate to the new, supported, installer through https://install.python-poetry.org.
Add Poetry to your PATH

The installer installs the poetry tool to Poetry’s bin directory. This location depends on your system:
- $HOME/.local/bin for Unix
- %APPDATA%\Python\Scripts on Windows
If this directory is not on your PATH, you will need to add it manually if you want to invoke Poetry with simply poetry.

Alternatively, you can use the full path to poetry to use it.
Check the installation

Once Poetry is installed you can execute the following:
```
poetry --version
```
If you see something like Poetry (version 1.2.0) then you are ready to use Poetry.
Configure the installation

By default, Poetry is installed into the user’s platform-specific home directory. 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 --preview option to install-poetry.py 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.2.0
curl -sSL https://install.python-poetry.org | POETRY_VERSION=1.2.0 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@master
```
Update Poetry

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
```
Warning

Poetry versions installed using the deprecated get-poetry.py installer will not be able to use this command to update to 1.2 releases or later. Migrate to using https://install.python-poetry.org or pipx.
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 -
```

Using pipx to install Poetry is also possible.

pipx is used to install Python CLI applications globally while still isolating them in virtual environments. This allows for clean upgrades and uninstalls.

Install Poetry
```
pipx install poetry
```
Update Poetry
```
pipx upgrade poetry
```
Uninstall Poetry
```
pipx uninstall poetry
```

Using pip to install Poetry is possible.

pip install --user poetry

Warning

Be aware that it will also install Poetry’s dependencies which might cause conflicts with other packages.

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 > /etc/bash_completion.d/poetry

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

# Zsh
poetry completions zsh > ~/.zfunc/_poetry

# Oh-My-Zsh
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry

# prezto
poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry

Note

You may need to restart your shell in order for the changes to take effect.

For zsh, you must then add the following line in your ~/.zshrc before compinit:

fpath+=~/.zfunc

For oh-my-zsh, you must then enable poetry in your ~/.zshrc plugins

plugins(
	poetry
	...
	)