// Tutorial //

How To Install Poetry to Manage Python Dependencies on Ubuntu 22.04

Published on October 20, 2022
Default avatar
By Tony Tran
Developer and author at DigitalOcean.
How To Install Poetry to Manage Python Dependencies on Ubuntu 22.04

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

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:

  1. 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:

  1. nano ~/.bashrc

Add the following line to the end of the file:

~/.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:

  1. source ~/.bashrc

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

  1. poetry --version
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.

  1. poetry new sammy_poetry

Next, navigate into your new project directory:

  1. 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:

  1. ls
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:

  1. 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:

  1. nano pyproject.toml
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:

  1. poetry add requests
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:

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:

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:

  1. poetry remove requests
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:

  1. poetry add requests@2.26.0
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:

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.

If you’ve enjoyed this tutorial and our broader community, consider checking out our DigitalOcean products which can also help you achieve your development goals.

Learn more here


About the authors
Default avatar
Tony Tran

author

Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!