Introduction

extras_require lets a Python package declare optional dependency groups such as dev, docs, or postgres. This is especially useful with editable installs because developers often want the package linked from the local source tree plus a specific optional toolset. The syntax is simple once you know where extras are declared and how pip install -e consumes them.

Define Extras in Package Metadata

In a classic setup.py project, extras are defined under extras_require.

1from setuptools import setup, find_packages
2
3setup(
4    name="sampleproj",
5    version="0.1.0",
6    packages=find_packages(),
7    install_requires=["requests"],
8    extras_require={
9        "dev": ["pytest", "black"],
10        "docs": ["sphinx"],
11        "postgres": ["psycopg[binary]"],
12    },
13)

The base install gets install_requires. Optional groups are installed only when explicitly requested.

Use Extras with Editable Install

To install the package in editable mode with one extra:

pip install -e ".[dev]"

To install multiple extras:

pip install -e ".[dev,docs]"

The . means “install the current directory as a package,” and the bracketed part selects extra dependency groups.

pyproject.toml Version

Modern projects often use pyproject.toml instead of setup.py. The concept is the same.

1[project]
2name = "sampleproj"
3version = "0.1.0"
4dependencies = ["requests"]
5
6[project.optional-dependencies]
7dev = ["pytest", "black"]
8docs = ["sphinx"]
9postgres = ["psycopg[binary]"]

The install command is unchanged:

pip install -e ".[dev]"

So the user-facing workflow remains stable even as packaging metadata format changes.

Why Editable Plus Extras Is Useful

Editable installs are convenient during development because code changes in the working tree are immediately reflected without reinstalling the package. Extras let each developer or CI job opt into the toolchain it needs.

Typical patterns:

• '.[dev] for tests, linters, formatters'
• '.[docs] for documentation builds'
• '.[postgres] for database-specific integration work'

This keeps the base package lightweight while still supporting richer workflows.

Requirements Files Versus Extras

Some teams ask whether extras should replace requirements files entirely. Usually they solve different problems.

• extras describe optional package capabilities and development roles
• requirements files pin concrete versions for reproducible environments

Many projects use both: extras for dependency grouping, requirements or lockfiles for exact version control.

Common Shell Quoting Issue

The extras syntax can be interpreted by the shell if not quoted correctly, especially in shells that treat brackets specially. The safest pattern is:

pip install -e ".[dev]"

If you omit quotes, behavior can vary depending on shell and platform.

Verifying the Install

After install, confirm the package resolves from your working tree and that extra tools are present.

python -c "import sampleproj; print(sampleproj.__file__)"
python -c "import pytest; print(pytest.__version__)"

This confirms both editable linkage and extra dependency installation.

Common Development Patterns

Many teams standardize on a few extras and document them in onboarding instructions:

• '.[dev] for local development'
• '.[test] for CI test jobs'
• '.[docs] for documentation builds'

This is cleaner than telling contributors to install a long list of individual packages manually, and it keeps optional dependency intent close to the package metadata.

Common Pitfalls

• Defining extras correctly but forgetting the bracket syntax on pip install -e.
• Omitting shell quotes and letting the shell interpret brackets.
• Using extras as a substitute for proper version pinning when reproducibility matters.
• Mixing old setup.py and new pyproject.toml packaging styles inconsistently.
• Assuming editable mode changes dependency resolution semantics beyond linking local source.

Summary

• Declare optional groups in extras_require or project.optional-dependencies.
• Install them in editable mode with pip install -e ".[extra]".
• Use comma-separated names for multiple extras.
• Keep extras for roles or capabilities, and use lockfiles or requirements for reproducibility.
• Quote the install target to avoid shell parsing issues.