Using Poetry

Installation

The official installation guide is very well written, and it is recommended to install via pipx. Installing Poetry generally should not pose any problems, as long as pipx is working properly.

Official Installation Guide

Basic Usage

Create a Project

poetry new poetry-demo

Poetry assumes your package contains a package with the same name as tool.poetry.name located in the root of your project. If this is not the case, populate tool.poetry.packages to specify your packages and their locations.

In the pyproject.toml file, the tool.poetry.name must match the name value. If they differ, you need to specify it using tool.poetry.packages

For example:

Project structure:

my_project/
├── my_project/  # This is the directory where your package code is located
│   ├── __init__.py  # Makes it a package
│   ├── some_module.py
└── pyproject.toml

1. Same as the name

[tool.poetry]
name = "my_project"

2. Different from the name, specify with tool.poetry.packages

[tool.poetry]
name = "my_project"

[tool.poetry.packages]
include = "src"

Existing Project Managed with Poetry

cd pre-existing-project
poetry init

Poetry Dependencies

Adding Dependencies

1. Modify the toml file

[tool.poetry.dependencies]
pendulum = "^2.1"

2. Use the command line add (this will automatically run install)

poetry add pendulum

Supported Dependency Formats in Poetry

caret

e.g. ^1.2.3 → >=1.2.3 <2.0.0

tilde

e.g. ~1.2.3 → >=1.2.3 <1.3.0

wildcard

e.g. 1.* → >=1.0.0 <2.0.0

Inequality

e.g. >= 1.2.0

When using poetry add, you can use the @ symbol, which is equivalent to ==, but you can also utilize Poetry’s modifiers

e.g.

poetry add django@^4.0.0

poetry add django@latest

poetry add django[bcrypt]@^4.0.0

Managing Dependencies

Poetry offers dependency groups to manage project dependencies, such as those used only for tests.

You can declare a dependency group using tool.poetry.group.<group>

For example:

[tool.poetry.group.test]  # This part can be left out

[tool.poetry.group.test.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"

This groups libraries like pytest and pytest-mock under the test group.

The Poetry documentation states:

Dependency groups (except the implicit main group) should include only the packages you need during development. They are installed only with Poetry. To declare a set of dependencies that add optional features at runtime, use extras. End users can install extras using pip.

Adding Dependencies to a Group

When using poetry add, add the --group (or -G) parameter

poetry add pytest --group test

If the dependency group does not exist, it will be created automatically.

Removing Dependencies from a Group

Use poetry remove to delete packages from a specific group

poetry remove mkdocs --group docs

Creating Optional Groups

You can add optional = true to mark a group as optional, so that it is not automatically installed with poetry install

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "*"

Installing/Excluding Groups

By default, all groups except those marked optional are installed automatically with poetry install

You can specify which dependency groups to include or exclude using the --with or --without options

poetry install --with docs

poetry install --without test,docs

When used together, --without takes precedence over --with. For example, the following command will install only the dependencies specified in the optional test group.

poetry install --with test,docs --without docs

If you want to install only the runtime dependencies of the project, use the --only main option:

poetry install --only main

If you want to install only the package at the project’s root and skip other dependencies, use the --only-root option.

poetry install --only-root

Synchronization – Installing Dependencies and Removing Unnecessary Packages

Poetry supports dependency synchronization, which ensures that the dependencies locked in the poetry.lock file are the only ones present in your environment by removing any unneeded packages.

You can use the --sync parameter with poetry install

poetry install --sync

This command will:

1. Remove extra packages
2. Install missing packages
3. Update outdated packages

It can be combined with the --with or --without options

poetry install --without dev --sync
poetry install --with docs --sync
poetry install --only dev

The primary dependencies are always installed. For example, if you have groups [main], [dev], [docs] and run poetry install --with docs --sync, then [main] and [docs] will be installed while [dev] will be omitted.