poetry

poetry#

The poetry project is yet another tool around Python packaging and dependency management. It is probably one of the best options if you also plan to publish your code to PyPI.

It uses a pyproject.toml file (as motivated by PEP 518 to store the project’s metadata and dependencies. An additional poetry.lock file keeps track of the precise package versions that are installed.

Tip

Always add pyproject.toml and poetry.lock to your version-control system. Not only does it help your collaborators to use the same package versions, but it also tracks all package updates in the git history.

Usage#

The best way to get started with poetry in an existing project, is to let it interactively create the pyproject.toml file by prompting you to input the relevant data.

$ poetry init

Then install all specified dependencies inside a virtual environment and create the corresponding poetry.lock file.

$ poetry install

In contrast to pipenv it will install the development dependencies by default, unless the --no-dev option is passed. In addition you can pass --no-root to skip the installation of the project’s package itself.

Tip

We recommend to instruct poetry to create the virtual environments inside the project’s .venv directory, instead of the shared virtualenvs.path.

poetry config virtualenvs.in-project true

You may later add other package requirements to the list.

$ poetry add <package>

To run the code of your project you can, as usual, activate the virtual environment, or use poetry helper commands.

$ poetry shell          # spawn shell with activated virtual environment
$ poetry run <command>  # run given command inside the virtual environment

Upgrading dependencies#

$ poetry update --dry-run   # list outdated packages
$ poetry update             # install available package updates

Other commands#

$ poetry show [--tree]                # list all packages [in a tree structure]
$ poetry install --remove-untracked   # uninstall all packages not specified in poetry.lock
$ poetry config --list                # show current configuration settings
Contents