Introduction

requirements.txt and setup.py solve related but different problems. A requirements file tells pip what to install into an environment, while setup.py historically describes a Python package itself: its metadata, its install dependencies, and how it should be built.

That distinction still matters, even though modern Python packaging now prefers pyproject.toml over directly running setup.py. If you confuse environment requirements with package metadata, dependency management gets messy fast.

What requirements.txt Is For

A requirements file is an environment installation list. It is commonly used for:

• local development environments
• deployment environments
• CI jobs
• repeatable application installs

Example:

1fastapi==0.116.1
2uvicorn==0.35.0
3sqlalchemy>=2.0,<3.0
4psycopg[binary]==3.2.9

Install it with:

pip install -r requirements.txt

The pip documentation defines requirements files as a list of items to be installed. That makes them a natural fit for applications where you want a specific environment assembled in a predictable way.

What setup.py Is For

setup.py belongs to Python packaging rather than plain environment setup. It describes a package that other people or projects can install.

A classic example looks like this:

1from setuptools import find_packages, setup
2
3setup(
4    name="acme-utils",
5    version="0.1.0",
6    packages=find_packages(),
7    install_requires=[
8        "requests>=2.32,<3",
9    ],
10    extras_require={
11        "dev": ["pytest>=8", "ruff>=0.6"],
12    },
13)

This tells packaging tools things such as:

• package name
• version
• package contents
• runtime dependencies
• optional extras

That is very different from saying "install these exact packages into this machine right now."

The Most Practical Rule of Thumb

Use requirements.txt for an environment. Use setup.py or, more commonly today, pyproject.toml for a distributable package.

That means:

• an application repository often has requirements.txt
• a reusable library often has package metadata with install_requires or project.dependencies
• many projects have both

For example, a library may declare broad runtime compatibility in package metadata, while the development repo uses a tighter requirements file for tests and linting.

Modern Python Packaging Note

The important modern nuance is that python setup.py install is now considered a deprecated practice by setuptools. The packaging role still exists, but current projects typically express it in pyproject.toml instead of relying on setup.py as the main entry point.

A modern equivalent looks like this:

1[build-system]
2requires = ["setuptools>=80", "wheel"]
3build-backend = "setuptools.build_meta"
4
5[project]
6name = "acme-utils"
7version = "0.1.0"
8dependencies = [
9  "requests>=2.32,<3",
10]

So the old comparison is still conceptually useful, but in new projects you should mentally read it as requirements.txt versus package metadata, often in pyproject.toml.

A Common Real-World Layout

Many healthy repositories separate concerns like this:

• 'pyproject.toml for package metadata and runtime dependencies'
• 'requirements.txt for a deployable application environment'
• 'requirements-dev.txt or an extra such as .[dev] for test and lint tooling'

That layout makes it obvious which dependencies are part of the package contract and which ones only support development workflows.

Common Pitfalls

• Using pip freeze output as a library's runtime dependency list. That usually pins far more than the library actually needs.
• Expecting requirements.txt to publish package metadata. It does not describe your package to packaging tools.
• Putting development-only tools into runtime package dependencies.
• Assuming setup.py is the modern way to invoke packaging commands. The script can still exist, but direct python setup.py ... usage is deprecated.
• Forgetting that applications and libraries often need different dependency strategies.

Summary

• 'requirements.txt is for installing a concrete environment with pip install -r.'
• 'setup.py historically describes a Python package and its dependencies.'
• In modern projects, pyproject.toml often replaces setup.py as the preferred packaging configuration.
• Applications often rely on requirements files, while reusable libraries rely on package metadata.
• Keeping environment pins separate from package metadata makes Python dependency management much easier to reason about.