Introduction

Many Python projects keep dependencies in both requirements.txt and setup.py, and that duplication often drifts over time. The safer pattern is to define a clear source of truth and generate one representation from the other in a controlled way. When done correctly, package installation remains predictable for users and maintainers.

Designing a fix that survives real usage requires more than one passing example. Treat each solution as a small interface contract with explicit assumptions, clear failure behavior, and repeatable verification steps.

Dependency Source Of Truth

1. Decide Which File Owns Runtime Dependencies

If you publish a package, treat setup.py or pyproject.toml metadata as canonical for install-time requirements. Keep development tools in separate extras or dev requirement files. This avoids mixing runtime constraints with local tooling needs.

1from pathlib import Path
2from setuptools import setup, find_packages
3
4
5def read_requirements(path: str):
6    lines = Path(path).read_text().splitlines()
7    cleaned = []
8    for line in lines:
9        line = line.strip()
10        if not line or line.startswith('#'):
11            continue
12        if line.startswith('-r'):
13            raise ValueError('Nested requirement files are not supported here.')
14        cleaned.append(line)
15    return cleaned
16
17install_requires = read_requirements('requirements-runtime.txt')
18
19setup(
20    name='example_pkg',
21    version='0.1.0',
22    packages=find_packages(),
23    install_requires=install_requires,
24)

The baseline implementation should stay intentionally simple. A small, transparent first version makes review faster and gives you a reliable reference point for later optimization.

2. Separate Runtime And Development Needs

Use dedicated files for runtime, test, and local development dependencies. Then expose extras in package metadata so users can opt into additional tooling intentionally. This makes dependency intent explicit and easier to audit.

1from setuptools import setup
2
3setup(
4    name='example_pkg',
5    version='0.1.0',
6    install_requires=['requests>=2.32.0'],
7    extras_require={
8        'dev': [
9            'pytest>=8.0.0',
10            'black>=24.0.0',
11        ],
12        'docs': [
13            'mkdocs>=1.6.0',
14        ],
15    },
16)
17
18# install with extras
19# pip install .[dev]

After baseline correctness, focus on operational hardening. Add input validation, timeout boundaries, and structured logging around critical branches so failures can be diagnosed quickly in real environments.

3. Validate Packaging In CI

Run packaging checks in continuous integration to catch mismatches early. Build a wheel, install it in a clean environment, and execute a minimal import smoke test. This workflow catches many hidden dependency mistakes before publishing.

Production confidence comes from repeatable checks. Add one normal-case test, one edge-case test, and one failure-path assertion in automation. This keeps behavior stable as dependencies and surrounding code evolve.

Where practical, include rollout safeguards such as feature toggles or rollback instructions. Recovery planning lowers deployment risk and shortens incident response time when unexpected runtime conditions appear.

A robust implementation also needs explicit operational boundaries. Document what inputs are supported, which failures are retriable, and which errors should fail fast. When these rules remain implicit, downstream callers invent their own assumptions and behavior drifts across services, scripts, or user interfaces. A short contract section close to the implementation often prevents weeks of confusion later.

Verification should include realistic data, not only toy examples. Add one scenario that mirrors production volume or shape, plus one malformed-input case and one dependency-failure case. These tests should run in automation on every change. Fast, repeatable checks are the most reliable way to keep behavior stable when dependencies change, runtime versions shift, or contributors refactor code with good intentions.

Finally, define release safety mechanics before rollout. Feature toggles, staged deployment, or a clear rollback procedure can turn a risky change into a controlled experiment. Even well designed code can fail under unexpected traffic patterns or infrastructure conditions. Teams that plan recovery ahead of time restore service faster and continue shipping with confidence.

Common Pitfalls

• Using one requirements file for runtime and local tooling, then shipping unnecessary dependencies to users.
• Parsing requirement files too loosely and accidentally including editable or nested directives in published metadata.
• Keeping duplicate dependency lists in multiple files without automation to synchronize them.
• Skipping wheel installation tests and assuming local editable installs match published behavior.
• Pinning all transitive dependencies aggressively and creating avoidable upgrade friction for downstream consumers.

Summary

• Pick one canonical dependency source and generate secondary files intentionally.
• Separate runtime dependencies from development and documentation tooling.
• Automate packaging validation with wheel install smoke tests in CI.
• Avoid ad hoc duplication that causes dependency drift over time.