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 2.7 or 3.5+. It is multi-platform and the goal is to make it work equally well on Windows, Linux and OSX.
Poetry provides a custom installer that will install
from the rest of your system.
osx / linux / bashonwindows install instructions #
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python -
windows powershell install instructions #
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -
get-poetry.pyinstaller is now deprecated, if you are currently using it you should migrate to the new, supported,
The installer installs the
poetry tool to Poetry’s
bin directory. This location depends on your system:
If this directory is not on your
PATH, you will need to add it manually
if you want to invoke Poetry with simply
Alternatively, you can use the full path to
poetry to use it.
Once Poetry is installed you can execute the following:
If you see something like
Poetry (version 1.2.0) then you are ready to use 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
POETRY_UNINSTALL environment variable before executing the installer.
python install-poetry.py --uninstall POETRY_UNINSTALL=1 python install-poetry.py
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:
POETRY_HOME=/etc/poetry python install-poetry.py
If you want to install prerelease versions, you can do so by passing
--preview option to
or by using the
POETRY_PREVIEW environment variable:
python install-poetry.py --preview POETRY_PREVIEW=1 python install-poetry.py
Similarly, if you want to install a specific version, you can use
--version option or the
python install-poetry.py --version 1.2.0 POETRY_VERSION=1.2.0 python install-poetry.py
You can also install Poetry for a
git repository by using the
python install-poetry.py --git https://github.com/python-poetry/poetry.git@master
Alternative installation methods #
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.
pipx install poetry
pipx upgrade poetry
pipx uninstall poetry
pip to install Poetry is possible.
pip install --user poetry
Updating Poetry to the latest stable version is as simple as calling the
self update command.
poetry self update
get-poetry.pyinstaller will not be able to use this command to update to 1.2 releases or later. Migrate to using the
If you want to install pre-release versions, you can use the
poetry self update --preview
And finally, if you want to install a specific version, you can pass it as an argument
poetry self update 1.2.0
Enable tab completion for Bash, Fish, or Zsh #
poetry supports generating completion scripts for Bash, Fish, and Zsh.
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.bash-completion # Bash (Homebrew) poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion # Fish poetry completions fish > ~/.config/fish/completions/poetry.fish # Fish (Homebrew) poetry completions fish > (brew --prefix)/share/fish/vendor_completions.d/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
zsh, you must then add the following line in your
oh-my-zsh, you must then enable poetry in your
plugins( poetry ... )