poetry add: Add a Dependency and Re-lock
Add a package and keep pyproject.toml and the lock in sync.
poetry add adds a dependency to pyproject.toml, resolves it, updates poetry.lock, and installs it. It is the right way to introduce a new package in a Poetry project.
What it does
Resolves the requested package against the existing constraints, writes it to the appropriate dependency group in pyproject.toml, updates the lockfile, and installs it.
Common usage
Terminal
poetry add requests
poetry add "django@^5.0"
poetry add --group dev pytest
poetry add "git+https://github.com/psf/requests.git#main"Common CI error: unsolvable constraint
If the new package conflicts with existing pins, Poetry reports the version solving failed. Loosen a constraint or pin a compatible version, then retry.
Terminal
# Failure:
# Because project depends on both A (^2.0) and B (^1.0)
# which requires A (<2.0), version solving failed.
# Fix: relax or pin to a compatible range
poetry add "A@>=1.9,<2.1"Options
| Option | Does |
|---|---|
| --group GROUP | Add to a dependency group |
| --dev | Add to the legacy dev group |
| --optional | Add as an optional (extra) dependency |
| --dry-run | Show what would change without doing it |
Related guides
poetry remove: Remove a DependencyHow poetry remove deletes a dependency from pyproject.toml and poetry.lock, the --group flag, and the error w…
poetry update: Upgrade Within ConstraintsHow poetry update upgrades dependencies to the newest versions allowed by pyproject.toml, updates the lock, a…
poetry lock: Resolve and Write poetry.lockHow poetry lock resolves dependencies and writes poetry.lock without installing, the --no-update flag, and th…