Table of Contents

Introduction

Poetry is a dependency manager for Python that is also capable of building and packaging your Python projects for distribution. As a dependency manager, it comes with tools for maintaining consistent and contained virtual environments. Additionally, it has tools to integrate with workflows using other forms of dependency management, such as requirements.txt.

In this tutorial you will install Poetry using the official installation script, set up a Poetry project with a virtual environment, then add and install your project's dependencies.

Prerequisites

poetry illustration for: Prerequisites

Step 1 — Installing Poetry

Poetry is installed using an official installation script provided on the Poetry website. This command will download the installation script, and then run the installation of Poetry onto your system. While this tutorial is for a Ubuntu 22.04 server, this installation script can be run on Linux, macOS, and Windows with WSL (Windows Subsystem for Linux) which can be installed through this tutorial. Enter the following command:

				
					curl -sSL https://install.python-poetry.org | python3 -
				
			
				
					…
[secondary_label Output]
Poetry (1.2.1) is installed now. Great!

To get started you need Poetry's bin directory (/home/<^>sammy<^>/.local/bin) in your `PATH`
environment variable.

Add `export PATH="/home/<^>sammy<^>/.local/bin:$PATH"` to your shell configuration file.

Alternatively, you can call Poetry explicitly with `/home/<^>sammy<^>/.local/bin/poetry`.
…

Once the installation completes, Poetry will prompt you to add its bin directory to your PATH in order to enable the use of poetry in your command line. On Ubuntu with Bash, this can be done by opening the ~/.bashrc file using nano or your preferred text editor:

				
					nano ~/.bashrc

Add the following line to the end of the file:

				
					[label ~/.bashrc]
. . .
export PATH="/home/<^>sammy<^>/.local/bin:$PATH"

Save and exit the file, with nano this can be done by pressing CTRL+X to exit and Y to save any changes.

Next, apply the changes to your current session:

				
					source ~/.bashrc

To check that the poetry command is now available, enter the following to display the current Poetry version:

				
					poetry --version
				
			
				
					[secondary_label Output]
Poetry (version <^>1.2.1<^>)

Now you have a working installation of Poetry, and can proceed to setting up a Poetry project.

Step 2 — Setting Up a Poetry Project

Start by creating a new Poetry project. This project will come with the virtual environment that will be used when installing and managing your dependencies. This tutorial will use the project name sammy_poetry, but feel free to choose your preferred name.

				
					poetry new <^>sammy_poetry<^>

Next, navigate into your new project directory:

				
					cd sammy_poetry

Your new Poetry project with the necessary boilerplate files is now created. To see your newly created project files, use a ls command:

				
					ls
				
			
				
					[secondary_label Output]
README.md dist pyproject.toml sammy_poetry tests

Note: If you have an existing project you wish to use, you can use a different command to get Poetry to recognize it as a project. Navigate to your existing project's directory, then enter this command:

				
					poetry init

This will create all the necessary files in your existing project, and you can continue with this tutorial as if it were a new project.

Step 3 — Adding Dependencies

Before you start adding dependencies to your project, you’ll start by inspecting and understanding the file that Poetry uses to hold your dependencies. In your Poetry project directory is an auto-generated pyproject.toml file that contains the list of your dependencies. Open and inspect it with the following:

				
					nano pyproject.toml
				
			
				
					[label pyproject.toml]
[tool.poetry]
name = "sammy-poetry"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "sammy_poetry"}]

[tool.poetry.dependencies]
python = "^3.10"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Along with your dependencies which are listed under tool.poetry.dependencies, there is also metadata under tool.poetry. Feel free to customize this metadata with your own info such as name, email, and project description. The build-system block currently contains specifications on how Poetry will build your packages, and can be left untouched for now.

One thing of note is that Python 3.10, while the latest version, can be demanding of resources and can be an issue depending on the system. Most Python libraries only require version 3.8 at a minimum. If you would like to change the Python version your project uses as a dependency, pinning version dependencies will be covered in Step 4 of this tutorial.

In its current state, your project has no dependencies other than Python itself. Poetry can add new dependencies to your project directly from the command line. By using the poetry add command, Poetry will both add a dependency line to your tool.poetry.dependencies block and install the dependency at the same time.

After inspecting your pyproject.toml file, exit your editor. As an example, you will be adding the popular Python HTTP library, requests, to your project's dependencies along with installing it using the add command. This library allows you to send HTTP requests with minimal boilerplate code and is useful for applications that interface through HTTP, though any package would suffice for purposes of this demonstration. Enter the following command:

				
					poetry add requests
				
			
				
					[secondary_label Output]
Creating virtualenv sammy-poetry-i9Ouy_MV-py3.10 in /home/sammy/.cache/pypoetry/virtualenvs
Using version ^2.28.1 for requests

Updating dependencies
Resolving dependencies... (0.3s)

Writing lock file

Package operations: 5 installs, 0 updates, 0 removals

 • Installing certifi (2022.9.24)
 • Installing charset-normalizer (2.1.1)
 • Installing idna (3.4)
 • Installing urllib3 (1.26.12)
 • Installing requests (2.28.1)

Along with adding to your pyproject.toml file and installing requests, the add command also handles the initialization of a virtual environment. Additionally, requests has dependencies of its own. Poetry automatically installs all these dependencies before installing requests itself.

Your pyproject.toml file will be updated with the following:

				
					[label pyproject.toml]
. . .
[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.28.1"
. . .

This ensures that requests is always installed. The ^ signifies that it would be the minimum acceptable version to be installed and higher versions would be acceptable as well.

Step 4 — Removing and Pinning Dependencies

In order to keep consistency between your currently installed dependencies and the dependencies you have listed in your pyproject.toml file, Poetry employs a lock file. Poetry reads directly from this file during the installation process, which means that directly editing your pyproject.toml file to change your dependencies may throw some errors or warnings such as this:

				
					[secondary_label Output]
. . .
Warning: poetry.lock is not consistent with pyproject.toml. You may be getting improper dependencies. Run `poetry lock [--no-update]` to fix it.
. . .

As such, if you need to remove a dependency or edit its version, you should use the poetry remove command. Although manually editing the pyproject.toml file is possible, you will have to account for the lock file and manually activate your virtual environment. So in the scenario that you want to change the version of requests, first remove it with this command:

				
					poetry remove requests
				
			
				
					[secondary_label Output]
Updating dependencies
Resolving dependencies... (0.1s)

Writing lock file

Package operations: 0 installs, 0 updates, 5 removals

 • Removing certifi (2022.9.24)
 • Removing charset-normalizer (2.1.1)
 • Removing idna (3.4)
 • Removing requests (2.28.1)
 • Removing urllib3 (1.26.12)

Now that requests is removed, next you can add it again as a pinned dependency. With dependencies, often you want to keep a library at a specific version for your project. This is often due to compatibility issues as libraries change over time, and can be beneficial to keeping your project consistent. This is called pinning dependencies.

As an example, you’ll pin requests to a version other than the latest, which is the default when running the add command. Instead, you’ll pin it to 2.26.0, which is an earlier, valid release as found in the PyPI history of requests:

				
					poetry add requests@2.26.0
				
			
				
					[secondary_label Output]
Updating dependencies
Resolving dependencies... (0.3s)

Writing lock file

Package operations: 5 installs, 0 updates, 0 removals

 • Installing certifi (2022.9.24)
 • Installing charset-normalizer (2.0.12)
 • Installing idna (3.4)
 • Installing urllib3 (1.26.12)
 • Installing requests (2.26.0)

Now, in your pyproject.toml file you will find:

				
					[label pyproject.toml]
. . .
[tool.poetry.dependencies]
python = "^3.10"
requests = <^>"2.26.0"<^>
. . .

This specifies that requests will always install specifically as version 2.26.0.

Conclusion

In this tutorial, you have installed Poetry and created a Poetry project, either from scratch or within an existing project. You’ve also added dependencies to it, then installed those dependencies within a virtual environment. Additionally, you removed a dependency before adding it as a pinned dependency in your project. Next you can explore more features of Poetry, with this tutorial on how to publish Python packages to PyPI using Poetry on Ubuntu 22.04.