Managing dependencies

Managing dependencies #

Poetry supports specifying main dependencies in the project.dependencies section of your pyproject.toml according to PEP 621. For legacy reasons and to define additional information that are only used by Poetry the tool.poetry.dependencies sections can be used.

See Dependency specification for more information.

Dependency groups #

Poetry provides a way to organize your dependencies by groups.

The dependencies declared in project.dependencies respectively tool.poetry.dependencies are part of an implicit main group. Those dependencies are required by your project during runtime.

Beside the main depdendencies, you might have dependencies that are only needed to test your project or to build the documentation.

To declare a new dependency group, use a tool.poetry.group.<group> section where <group> is the name of your dependency group (for instance, test):

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

Optional groups #

A dependency group can be declared as optional. This makes sense when you have a group of dependencies that are only required in a particular environment or for a specific purpose.

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

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

Optional groups can be installed in addition to the default dependencies by using the --with option of the install command.

poetry install --with docs

Adding a dependency to a group #

The add command is the preferred way to add dependencies to a group. This is done by using the --group (-G) option.

poetry add pytest --group test

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

Installing group dependencies #

By default, dependencies across all non-optional groups will be installed when executing poetry install.

You can exclude one or more groups with the --without option:

poetry install --without test,docs

You can also opt in optional groups by using the --with option:

poetry install --with docs

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

Finally, in some case you might want to install only specific groups of dependencies without installing the default set of dependencies. For that purpose, you can use the --only option.

poetry install --only docs

poetry install --only main

poetry install --only-root

Removing dependencies from a group #

The remove command supports a --group option to remove packages from a specific group:

poetry remove mkdocs --group docs

Synchronizing dependencies #

Poetry supports what’s called dependency synchronization. Dependency synchronization ensures that the locked dependencies in the poetry.lock file are the only ones present in the environment, removing anything that’s not necessary.

This is done by using the --sync option of the install command:

poetry install --sync

The --sync option can be combined with any dependency groups related options to synchronize the environment with specific groups. Note that extras are separate. Any extras not selected for install are always removed, regardless of --sync.

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

Layering optional groups #

When you omit the --sync option, you can install any subset of optional groups without removing those that are already installed. This is very useful, for example, in multi-stage Docker builds, where you run poetry install multiple times in different build stages.