What does a constraints file passed to pip with `-c` do that a requirements file with `-r` does not?

### The one-sentence difference `-r` says *install these*. `-c` says *and if you install this, it must be this version*. Everything else follows from that. ### Why the distinction matters The motivating case is a transitive dependency. Your service imports `frame-tools`, which in turn requires `clockdrift`. A `clockdrift` release goes out with a defect. You do not import `clockdrift`, so adding it to your own dependency list would be a lie: it announces a direct relationship that does not exist, and a future reader has no way to tell it was added only to dodge a bad release. Written as a constraint instead, the intent is legible -- *whatever pulls this in, do not let it be that version* -- and the entry becomes inert the day nothing needs the package any more. The second case is scale. A platform team can publish one constraints file expressing organisation-wide floors -- minimum versions that carry security fixes -- and every service passes it alongside its own requirements. Nobody has to enumerate which services happen to depend on what; the file only bites where the package is present. ### How pip consumes it ``` python -m pip install -r requirements.txt -c constraints.txt ``` Both flags may be repeated, and the constraint entries are merged into the resolution as extra bounds. A constraints file is a plain text file of requirement specifiers, so ranges, exact pins and environment markers all work: `clockdrift!=0.4.3`, `clockdrift>=0.4.4`, `clockdrift==0.4.2; python_version < "3.12"`. The restrictions come straight from the semantics. A constraint has to name a distribution -- an entry pip cannot associate with a name has nothing to bound. Editable entries are rejected, because installing a local project in place is a demand, not a bound. And a constraint that matches nothing produces no error, since nothing being installed is a perfectly valid outcome. ### Where teams misuse it **As a lockfile.** Copying pinned output into a constraints file and installing with only `-c` installs nothing at all -- there are no demands. Even paired with `-r`, the result is weaker than a lock: because unmatched constraints are silent, the file can rot for months while everyone believes it is pinning something. A lock is a *complete* record of a resolution; a constraints file is a *partial* bound on one. **As a substitute for fixing the direct dependency.** If a constraint is the only thing keeping a service on an old release of something it genuinely imports, that belongs in the project's own dependency ranges where a reviewer will see it. **Expecting it to force an upgrade.** A floor in a constraints file does not install the package or pull it in; it only rules out versions below the floor when something else asks for it. If the requirement is that a package be present at a minimum version, that is a requirement, not a constraint. ### The mental model to keep Think of the resolver as solving a set of equations. `-r` adds equations that must be satisfied. `-c` narrows the domain of a variable without asserting that the variable appears in the system. Both shape the answer; only one of them can create work.