Poetry is one of Python's dependency managers and package managers that is considered more standard than Pipenv. According to its documentation, it is a powerful tool that allows you to have a deterministic build each time.

Poetry uses existing virtual environments or creates its own. To start using poetry, let's begin by installing it.

The way I like to install poetry is through Pipx. If you do not know what Pipx is or what it does, take a look at this article https://siddhibajracharya.hashnode.dev/start-using-pipx. After setting up Pipx, you can install Poetry like any other Python package. If you install Poetry using Pipx, you can access the command line tools of Poetry globally.

Installation

Let's start by installing poetry:

pipx install poetry.

You can create new projects using poetry by running the following command:

Creating new projects

poetry new totally-awesome-project

A new folder called totally-awesome-project will be created and its file structure will look something like this:

Inside this project folder, you will see some files, but the power of Poetry comes from pyproject.toml file. It is the file that is used to manage, track and resolve the dependencies for our awesome project. The file looks like this initially.

[tool.poetry]
name = "totally-awesome-project"
version = "0.1.0"
description = ""
authors = ["siddhi <siddhi.47.skb@gmail.com>"]
readme = "README.md"
packages = [{include = "totally_awesome_project"}]

[tool.poetry.dependencies]
python = "^3.8"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

To activate the virtual environment, you need to go into the newly created project directory, i.e. totally-awesome-project and run the following command:

cd totally-awesome-project
poetry shell

This will create a new virtual environment in ~/.cache/pypoetry/virtualenvs/.

Installing packages

Once you activate your virtual environment, you will be able to install packages. Let's install pandas:

poetry add pandas

[tool.poetry]
name = "totally-awesome-project"
version = "0.1.0"
description = ""
authors = ["siddhi <siddhi.47.skb@gmail.com>"]
readme = "README.md"
packages = [{include = "totally_awesome_project"}]

[tool.poetry.dependencies]
python = "^3.8"
pandas = "^2.0.1"

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

If you install packages using poetry, you will see that your pyproject.toml file gets updated. You will also see a new file called poetry.lock file. poetry.lock file is updated every time you add new modules to your project. You can think of it as a dependencies for your dependencies. If you add pandas to your project, then it is also necessary to mention the dependencies for pandas. poetry.lock is a file that ensures this. Consider this an upgrade for requirements.txt file that we are familiar with.

Building from poetry

Now, you have installed all the required packages and now you want to distribute them. Make sure that you have both your pyproject.toml file and poetry.lock file. Then run:

poetry install

This command will download and install packages listed on your pyproject.toml file and will install the specific versions of dependencies of these packages by referring to poetry.lock the file. If you only have pyproject.toml a file, then Poetry will install the latest versions for all your dependencies. In a way, `poetry.lock file locks the version of dependencies required for your packages.

In this way, you are guaranteed to have deterministic builds every time.