poetry add: Add a Dependency Command Reference

Add a package and keep pyproject.toml and the lock in sync.

poetry add resolves a new dependency, writes it to pyproject.toml, updates poetry.lock, and installs it. It is the right way to introduce a package in a Poetry project.

Common flags / usage

poetry add requests -- add a runtime dependency
poetry add "django@^5.0" -- pin a version constraint
--group dev -- add to a dependency group
--optional -- add as an extra
--dry-run -- preview the change without applying it

Example

shell

# Usually run locally and committed, not in CI:
poetry add --group dev pytest pytest-cov
poetry add "fastapi@^0.115"

In CI

A bare conflict ("version solving failed") means the new package clashes with existing pins -- relax a constraint or pin a compatible range. Commit the updated pyproject.toml and poetry.lock so CI installs the same set.

Key takeaways

poetry add updates pyproject.toml, the lock, and installs in one step.
Use --group to target dev or other dependency groups.
--dry-run previews resolution before committing the change.

Related guides

poetry install: Install from Lock Command ReferenceReference for poetry install in CI: installing from poetry.lock, the --no-root, --only, and --no-interaction… poetry lock: Resolve the Lockfile Command ReferenceReference for poetry lock in CI: resolving dependencies into poetry.lock without installing, the consistency… poetry build: Build Artifacts Command ReferenceReference for poetry build in CI: producing a wheel and sdist into dist/ from pyproject.toml, the --format fl…