requirements.txt is a plain text list of packages, optionally with version specifiers and hashes, consumed by pip. It is simple and widely understood but has no standard place for project metadata, build system configuration, optional extras, or entry points. pyproject.toml, introduced by PEP 518 and extended by PEP 621, is the modern standard for declaring a project's build backend, metadata such as name and version, dependencies, optional dependency groups, and tool configuration. Pip can install from pyproject.toml when a build backend such as setuptools, hatchling, poetry-core, or flit is declared. Libraries should prefer pyproject.toml because it defines a proper installable package. Applications often still use requirements.txt or a lock file for deployment, because it captures the exact resolved versions of the full dependency tree. The pragmatic pattern is pyproject.toml for the project definition and a generated lock file for reproducible installs.

1
requirements.txt: flat list, easy to use, no build backend or metadata. Good for simple deployments and lock snapshots.
2
pyproject.toml: build-system, project metadata, dependencies, optional extras, entry points, and tool config in one file.
3
PEP 517 defines the build backend interface; PEP 518 defines pyproject.toml; PEP 621 defines the [project] table.
4
Tools: poetry, pdm, hatch, and flit all use pyproject.toml and add lock files.
5
Trade-off: pyproject.toml is richer but requires a build backend and a tool that understands it. requirements.txt works with everything and is trivial to audit.
6
Common mistake: keeping setup.py only and no pyproject.toml, which limits modern tooling and build reproducibility.
7
Common mistake: hand-editing requirements.txt and losing the distinction between direct dependencies and transitive ones.
8
Version note: PEP 621 support is available in setuptools 61+, poetry 1.2+, and most modern tools. Older tooling may require setup.cfg or setup.py.

javascript

Scenario Questions

0-2 years experience

1You need to install dependencies for a project. Which file do you use with pip?
2What is the purpose of the [build-system] table in pyproject.toml?

2-5 years experience

1You are publishing a library to PyPI. Why is pyproject.toml preferred over setup.py?
2You need optional development dependencies. How do you declare them in pyproject.toml?

5-8 years experience

1You need reproducible installs in CI. How do you combine pyproject.toml with a lock file?
2You have a legacy setup.py project and want to migrate. What are the steps and risks?

8+ years experience

1Design a packaging and release strategy for a multi-package repository with shared dependencies, versioning, and CI publishing.
2Explain how PEP 517, 518, 621, and lock files interact across tools like pip, poetry, and pdm, and how to standardize across an organization.

Follow-up Questions

How do lock files relate to pyproject.toml and requirements.txt?
When would you still choose requirements.txt over pyproject.toml?

Sharethis question

Share via WhatsApp, X, Facebook, LinkedIn or copy link. Open Graph preview enabled.

What is the difference between requirements.txt and a modern pyproject.toml-based dependency specification?

Difficulty: 6/10

Requirements Txt, Pyproject Toml, PEP 517, PEP 621, Dependency Management

requirements.txt lists packages for an environment; pyproject.toml declares project metadata and build config

1
requirements.txt: flat list, easy to use, no build backend or metadata. Good for simple deployments and lock snapshots.
2
pyproject.toml: build-system, project metadata, dependencies, optional extras, entry points, and tool config in one file.
3
PEP 517 defines the build backend interface; PEP 518 defines pyproject.toml; PEP 621 defines the [project] table.
4
Tools: poetry, pdm, hatch, and flit all use pyproject.toml and add lock files.
5
Trade-off: pyproject.toml is richer but requires a build backend and a tool that understands it. requirements.txt works with everything and is trivial to audit.
6
Common mistake: keeping setup.py only and no pyproject.toml, which limits modern tooling and build reproducibility.
7
Common mistake: hand-editing requirements.txt and losing the distinction between direct dependencies and transitive ones.
8
Version note: PEP 621 support is available in setuptools 61+, poetry 1.2+, and most modern tools. Older tooling may require setup.cfg or setup.py.