Skip to content

How to use Poetry to manage dependencies in Python

Learn how Poetry can be initialized in a project and used to resolve dependencies.

The Python programming language has tools for managing environment and interpreter versions such as venv and pyenv respectively. We have talked about virtual environments in Python and how to use them in this blog post.

Languages like Node.js, Go and Rust have their own utility CLI tool for helping with environment and dependency management for a project. Python lacks a default tool that can do dependency management hence third-party tools need to be used, one such tool is poetry.

In this article, you will get an overview of how poetry works and how to manage dependencies in poetry.

Poetry Installation

Linux/Mac/bashonwindows users should execute the following command in a terminal:

curl -sSL | python -

For windows powershell users:

(Invoke-WebRequest -Uri -UseBasicParsing).Content | python -

To verify if poetry is successfully installed, open a new terminal and check for the version of poetry:

poetry โ€“version

Creating a Poetry project

To create a new poetry initialized project, we use the command

poetry new my-poetry-project

Executing this command will create a folder with the following tree structure

โ”œโ”€โ”€ my_poetry_project
โ”‚   โ””โ”€โ”€
โ”œโ”€โ”€ pyproject.toml
โ”œโ”€โ”€ README.rst
โ””โ”€โ”€ tests

If a project is already created, use poetry init to initialize poetry.

By default, poetry creates a python package with an appropriate name. The file pyproject.toml is used by poetry to keep a track of project info, python version, development dependencies and other externally installed packages. It is worth noting that the dependencies of dependencies is not stored in pyproject.toml file.

In Node.js a package-lock.json file is created to lock the dependency versions during installation similarly, a poetry.lock file is created by poetry to lock dependency versions. Storing the version of every package helps poetry to resolve dependency conflicts while installing/updating packages. Also, when another user will use poetry to install dependency the exact same packages would be downloaded and installed.

Manage virtual environments with Poetry

One of the core features of poetry is the usage of the virtual environment to isolate the project runtime from the global python runtime. If a user is using poetry inside a virtual environment then poetry keeps using it else it creates a separate virtual environment for the project with the default python version of the computer.

List available environments:

poetry env list

Create/use an environment:

Specify Python version for environment creation/use. Users can use the path to an environments python interpreter.

poetry env use 3.6

Remove an environment:

poetry env remove env-name

Add packages with Poetry

When a new package is installed both, pyproject.toml and poetry.lock, are updated. Installation is done using the poetry add package-name command, users can also specify version constraints such as:

  • poetry add pendulum@^2.0.5
  • poetry add "pendulum>=2.0.5"
  • poetry add pendulum==2.0.5

To install multiple packages, specify package names in a sequence such as

poetry add pandas numpy matplotlib 

Remove packages with Poetry

Removing package from the project is easy. Whenever a package is removed its unused dependencies are removed too, updating pyproject.toml and poetry.lock. To remove multiple packages, specify package names in a sequence.

poetry remove pandas

Update packages with Poetry

Similar to removing a package, updating a package updates pyproject.toml and poetry.lock with new versions and updated dependencies. To update multiple packages, specify package names in a sequence.

poetry update pandas

Install all project dependencies with Poetry

To setup a newly cloned project with poetry initialized, use the following command

poetry install

If poetry.lock file is not available, poetry will read the pyproject.toml file, resolve the dependencies, install the packages and create lock file.

If poetry.lock file is available, poetry will read from lock file to ensure same package versions are installed as other users.

FREE VS Code / PyCharm Extensions I Use

โœ… Write cleaner code with Sourcery, instant refactoring suggestions: Link*

PySaaS: The Pure Python SaaS Starter Kit

๐Ÿš€ Build a software business faster with pure Python: Link*

* These are affiliate link. By clicking on it you will not have any additional costs. Instead, you will support my project. Thank you! ๐Ÿ™