Introduction

In npm, --save-dev records a dependency that should exist for development and testing but not necessarily runtime production. Python has the same conceptual split, but pip does not provide one universal flag that updates every project manifest the way npm does. In practice, you model dev dependencies through requirements files or optional dependency groups in pyproject.toml.

Why pip Has No Single Direct Flag

pip is primarily an installer and resolver, not a full project metadata manager. Python projects use multiple packaging workflows, so dependency recording is done in project files.

Common approaches:

• requirements.txt and requirements-dev.txt.
• pyproject.toml optional dependency groups.
• Tool-specific groups in Poetry, Hatch, or PDM.

So the equivalent of npm dev dependency behavior is achieved through structure, not a single command switch.

Requirements File Pattern

A traditional and widely used setup is splitting runtime and development requirements.

requirements.txt for runtime:

fastapi==0.116.0
uvicorn==0.34.0

requirements-dev.txt for development tools:

1-r requirements.txt
2pytest==8.3.5
3ruff==0.6.5
4mypy==1.15.0

Install dev environment with:

pip install -r requirements-dev.txt

This is straightforward, explicit, and compatible with most CI pipelines.

pyproject.toml Optional Dependencies

Modern packaging often defines optional groups directly in metadata.

1[project]
2name = "sample-app"
3version = "0.1.0"
4dependencies = [
5  "fastapi>=0.116",
6  "uvicorn>=0.34"
7]
8
9[project.optional-dependencies]
10dev = [
11  "pytest>=8",
12  "ruff>=0.6",
13  "mypy>=1.15"
14]

Then install local package with dev extras:

pip install -e ".[dev]"

This is conceptually close to npm dependency groups and works well in package-centric repositories.

Comparing Mental Models: npm and pip

npm workflow often combines install and manifest update in one command. Python separates concerns more explicitly.

Typical Python flow:

1. Edit project dependency files.
2. Run pip install from those files.
3. Commit updated dependency declarations.

This may feel less automatic, but it is clear and tool-agnostic.

CI and Production Separation

Whatever mechanism you choose, the key goal is keeping production images lean.

Recommended split:

1# test pipeline
2pip install -r requirements-dev.txt
3pytest
4
5# production runtime
6pip install -r requirements.txt

This prevents linters, formatters, and test frameworks from bloating runtime containers.

Locking and Reproducibility

Dev dependency groups can drift quickly without pinning strategy. Use constraints, lock tools, or compiled requirements for deterministic builds.

Practical safeguards:

• Pin important tool versions.
• Validate installs in clean virtual environments.
• Use the same install commands locally and in CI.

Reproducibility matters more than whether you chose file-based or extras-based grouping.

Tool-Specific Commands

If your project uses a higher-level manager, you may get dedicated commands for dev groups. Those are valid, but they are manager-specific workflows layered on top of Python packaging conventions.

When documentation says “pip equivalent,” the most accurate answer is to model dev dependencies in project metadata and install those groups explicitly.

Migration Plan for Existing Projects

If all dependencies are currently mixed in one file:

1. Identify runtime-only packages.
2. Move test and lint tools to dev group.
3. Update CI scripts accordingly.
4. Verify app runs with runtime-only set.

This cleanup improves deployment confidence and reduces unnecessary runtime attack surface.

Common Pitfalls

• Expecting pip to auto-record dependencies in a project manifest with one flag.
• Mixing runtime and development tools in one unstructured requirements file.
• Using different install commands in local and CI environments.
• Defining extras but forgetting to document install usage.
• Skipping version pinning and seeing inconsistent behavior across machines.

Summary

• Python has dev dependency concepts, but not one universal pip flag identical to npm --save-dev.
• Common solutions are split requirements files or optional dependency groups.
• pip install -r requirements-dev.txt and pip install -e ".[dev]" are practical equivalents.
• Keep runtime and development dependency sets intentionally separate.
• Reproducible installs and clear documentation matter more than command symmetry with npm.