How To Install Poetry to Manage Python Dependencies on Ubuntu 22.04

Published on October 20, 2022
How To Install Poetry to Manage Python Dependencies on Ubuntu 22.04


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.


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:

. . .
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
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
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
name = "sammy-poetry"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"
packages = [{include = "sammy_poetry"}]

python = "^3.10"

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

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

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

. . .
python = "^3.10"
requests = "2.26.0"
. . .

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


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.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar
Tony Tran


Still looking for an answer?

Ask a questionSearch for more help

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!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel