What are Optional Dependencies and Dependency Groups?

Optional Dependencies: End-User Features

Optional dependencies, defined in pyproject.toml under [project.optional-dependencies], are designed to:

• Package optional features that some users may want
• Allow users to install specific feature sets using the pip install package[extra] syntax
• Get published to PyPI along with the package

For example:

[project.optional-dependencies]
aws = [
    "boto3>=1.26.0",
    "s3fs>=2023.1.0",
]
visualization = [
    "matplotlib>=3.7.0",
    "seaborn>=0.12.0",
]

This allows users to choose the features they need:

pip install mypackage[aws]  # Only AWS-related features
pip install mypackage[visualization]  # Only visualization features

Dependency Groups: Developer Tools

Dependency groups, defined under [dependency-groups], are meant for:

• Managing development-time dependencies
• Organizing tools needed for different development tasks
• Keeping the published package lean

A typical example might look like:

[dependency-groups]
test = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
]
lint = [
    "ruff>=0.1.0",
    "mypy>=1.0.0",
]

These dependencies stay local to development and never get published to PyPI.

The distinction between optional dependencies and dependency groups represents a key evolution in Python package management, particularly as projects grow in complexity. This evolution reflects increasing sophistication in how the Python ecosystem handles different types of dependencies.

The Key Difference

Optional dependencies (project.optional-dependencies) and dependency groups (dependency-groups) may appear similar at first glance, but they serve fundamentally different purposes:

• Optional dependencies are meant to be published with your package, providing additional features that end-users can opt into
• Dependency groups are development-time dependencies that never get published with your package

This distinction becomes increasingly important as projects scale and development workflows mature.

Best Practices

Several key guidelines help maintain clean dependency management:

• Use optional dependencies for features that add significant value but aren’t core functionality
• Use dependency groups for development tools that users don’t need to know about
• Consider the maintenance burden of each optional feature exposed

Further Reading

• PEP 621 - Storing project metadata in pyproject.toml
• PEP 735 - Dependency Groups in pyproject.toml
• Python Packaging User Guide - Declaring Dependencies