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.