Managing dependencies #
Dependency groups #
Poetry provides a way to organize your dependencies by groups. For instance, 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
<group> is the name of your dependency group (for instance,
[tool.poetry.group.test] # This part can be left out [tool.poetry.group.test.dependencies] pytest = "^6.0.0" pytest-mock = "*"
All dependencies must be compatible with each other across groups since they will be resolved regardless of whether they are required for installation or not (see Installing group dependencies).
Think of dependency groups as labels associated with your dependencies: they don’t have any bearings on whether their dependencies will be resolved and installed by default, they are simply a way to organize the dependencies logically.
The dependencies declared in
tool.poetry.dependencies are part of an implicit
[tool.poetry.dependencies] # Default dependency group httpx = "*" pendulum = "*" [tool.poetry.group.test.dependencies] pytest = "^6.0.0" pytest-mock = "*"
A note about the
Any dependency declared in the
dev-dependencies section will automatically be added to a
So the two following notations are equivalent:
[tool.poetry.dev-dependencies] pytest = "^6.0.0" pytest-mock = "*"
[tool.poetry.group.dev.dependencies] pytest = "^6.0.0" pytest-mock = "*"
Poetry will slowly transition away from the
dev-dependencies notation which will soon be deprecated,
so it’s advised to migrate your existing development dependencies to the new
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
option of the
poetry install --with docs
Adding a dependency to a group #
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 groups will be installed when executing
You can exclude one or more groups with the
poetry install --without test,docs
You can also opt in optional groups by using the
poetry install --with docs
If you only want to install the default, non-grouped, dependencies, you can do so
poetry install --default
Finally, in some case you might want to install only specific groups of dependencies
without installing the default dependencies. For that purpose, you can use
poetry install --only docs
Removing dependencies from a group #
remove command supports a
to remove packages from a specific group:
poetry remove mkdocs --group docs
Synchronizing dependencies #
Poetry supports what’s called dependency synchronization. What this does is ensuring
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
poetry install --sync
--sync option can be combined with any dependency groups related options
to synchronize the environment with specific groups.
poetry install --without dev --sync poetry install --with docs --sync poetry install --only dev
--syncoption replaces the
--remove-untrackedoption which is now deprecated.