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.
sudo
privileges and a firewall enabled.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:
. . .
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
OutputPoetry (version 1.2.1)
Now you have a working installation of Poetry, and can proceed to 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
OutputREADME.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.
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
[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
OutputCreating 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:
. . .
[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.
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:
- poetry remove requests
OutputUpdating 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
OutputUpdating 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:
. . .
[tool.poetry.dependencies]
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.
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!