Using Poetry Dependency Groups to Separate Dev, Test, and Production Dependencies

Use Poetry dependency groups to keep dev, test, and production packages separate

Poetry lets you define named groups of dependencies in pyproject.toml. Packages in a group are installed only when you explicitly request that group, which keeps your production lock file free of testing or development tools.

Worked example

[tool.poetry]
name = \"example-app\"
version = \"0.1.0\"
description = \"\"
authors = [\"Your Name <you@example.com>\"]

[tool.poetry.dependencies]
python = \"^3.9\"
requests = \"^2.28\"

[tool.poetry.group.dev.dependencies]
pytest = \"^7.0\"
black = \"^23.0\"

[tool.poetry.group.test.dependencies]
pytest-cov = \"^4.0\"
hypothesis = \"^6.0\"

[tool.poetry.group.production.dependencies]
# Typically empty; production deps live in the main [tool.poetry.dependencies] section

Run the following commands in the project root (you need read/write access to the directory):

• poetry install – installs only the main dependencies and any groups marked as default (none in this example).
• poetry install --with dev – adds the dev group (pytest, black) to the virtual environment.
• poetry install --with dev,test – installs both development and testing groups.

After each install you can verify what is present:

poetry show --tree   # shows dependency tree
poetry show -D       # lists all defined groups and which packages belong to each

Poetry updates poetry.lock with exact hashes for every package that was installed, ensuring reproducibility across machines.

Limits and common mistakes

• Mixing pip and Poetry. Running pip install inside a Poetry virtual environment writes directly to site-packages and bypasses the lock file, causing version drift. Use poetry add or poetry install instead.
• Forgetting to lock. After adding or removing a package with poetry add or editing pyproject.toml manually, run poetry lock to refresh the lock file; otherwise the lock may become outdated.
• Version constraints. If the Python version specified in [tool.poetry.dependencies] conflicts with a group’s dependency, poetry install will fail. Keep constraints compatible or use poetry add --group dev python=\"^3.10\" to override per‑group.
• Groups are not published. Packages defined only in a group are not included when you run poetry build; they stay local to development workflows.
• Repeated --with flags. Each poetry install call must repeat the groups you need; there is no persistent \"active group\" setting.

Practical way to check that groups are correctly isolated:

1. Run poetry install --with dev.
2. Execute poetry show -D and confirm that only the dev group lists pytest and black.
3. Check poetry.lock for a section named [[package]] entries for those packages and verify the content-hash matches across machines.