Include the pip-tools version in the header of pip-compiled requirements.txt files

[jayaddison]

What's the problem this feature will solve?

It can be useful to replicate the pip-compile environment previously used to autogenerate a requirements.txt file. In particular: re-using the same version of pip-compile is likely to minimise the effect of any other local changes applied.

To phrase that conversely: when people attempt to regenerate a requirements.txt file using a much more recent version of pip-tools, it's likely that the output will include extraneous differences that may make it more difficult to notice any unrelated/unexpected changes.

It is currently not readily apparent from the contents of a pip-compile'd requirements.txt file what version of pip-tools was used to compile it.

An optional header can be added, but it contains only the major/minor Python version used, but not the pip-tools version.

Describe the solution you'd like

I'd like to suggest adding the pip-tools version to the header output when the --header option is provided to pip-compile.

As a real-world example, to support some commentary in #2245 I'd like to try replicating the docs/requirements.txt file used in this repository. It is non-trivial for me to figure out what version of pip-tools was used, and that makes it more difficult for me to respond in a timely and accurate manner.

The version number could be the same one produced by pip-compile --version -- e.g. the 7.5.1.dev42+dirty below:

$ pip-compile --version
pip-compile, version 7.5.1.dev42+dirty

Alternative Solutions

Add pip-tools to pyproject.toml and suggest/require that developers use this version when updating autogenerated files.

This could be supported by a continuous integration check that notifies when the compiled requirements.txt content diverges from the version committed to the source repository.

Additional context

Somewhat similar to #2168, except that that issue suggests adding a timestamp; I think that could be useful in some circumstances, but for the use case here I would prefer a version number.

[shivamtiwari3]

Thanks for the thoughtful review of #2352. I'd like to re-engage on this properly by answering your questions before any code is written.

1. Should pip-compile do this at all?

I think yes, for reproducibility. The header already includes the Python version for exactly this reason — if you pick up someone else's requirements.txt you can tell what Python compiled it. But you still can't tell what pip-tools version compiled it, which matters because pip-tools itself affects resolution (e.g. constraint handling, annotation format, default flags). Lockfile tools like Poetry and PDM embed their own version in their lock files for the same reason. The pip-tools header is the natural place to do this.

2. Should the behavior be always-on, opt-in, or opt-out?

I'd argue always-on when --header is enabled (which is the default). Reasons:

• --no-header already exists as a complete escape hatch for users who don't want any tooling metadata in their output.
• Adding a separate --no-pip-tools-version flag introduces combinatorial complexity (--header × --[no-]pip-tools-version) for a minimal benefit.
• The Python version is already always-on, so the pip-tools version is a natural peer.

Opt-out via a new flag is viable but feels over-engineered given that --no-header already covers the "I don't want tool metadata" use case.

3. Should pip-compile update the header when the pinned requirements do not change, but the current version does not match the one in the header?

Yes — the header should be updated. If I compiled with 7.4.0 and re-run with 7.5.0 with the same inputs, the header currently says 7.4.0 which is inaccurate. Since the purpose of recording the version is reproducibility, a stale version number is worse than no version number at all. pip-compile already rewrites files when anything changes; a version mismatch in the header should count as a change.

---

Happy to implement this if the above reasoning aligns with your thinking. I'll follow the proper contribution workflow (PR template, changelog entry, tests for the new header format and the version-mismatch rewrite scenario).

[jayaddison]

Thanks @shivamtiwari3 - just to clarify: the review you mention was by @sirosen. Thanks both of you for exploring this request, and in particular, the unspecified aspects of it.

Although I'm less certain whether any use of LLM-generated code and commentary in this case is a problem (I'm biased!), I do agree with the reasoning and, to me, the pull request also looks good to me from an initial browse.

If it'd be helpful I can perform some local testing/QA of the changes from #2352 and/or of a future pull request.

[sirosen]

I remain extremely skeptical about the utility and benefit of this feature, vs the noisy annoyance that it would be for many users.

I use Poetry pretty heavily at $WORK, and I find the version number changing in the lockfile to be noise -- it has never (in 7+ years of using Poetry) been significant in tracking down a bug. Perhaps that's just a limitation of my own experience.

I've never seen anyone recording their pip-tools version in a file, which is already possible today.
For example, are there justfiles, Makefiles, or tox or nox configurations in which people run pip-compile --version > .pip-tools-version.txt? If the version number is important to record, people would already be recording it, wouldn't they?

I also question whether or not there is meaningful reproducibility to be gained here. Unless you run a private index server, pip-tools runs change as the state on pypi changes. That's not just new releases (which we are gaining options to control by date), but also yanks and deletions. Plus, this doesn't record the pip version being used, which is enormously important! So what is the scenario in which this is the key piece of information needed?

It is not valid to treat the Python version as analogous. That goes into marker evaluation. That analogy is an argument for having a mode to record all of the marker environment information, like the platform, arch, etc. And if variants are standardized, fully recording the environment becomes genuinely impossible, so I'm not sure that it's wise to pursue.

Although I'm less certain whether any use of LLM-generated code and commentary in this case is a problem (I'm biased!), I do agree with the reasoning and, to me, the pull request also looks good to me from an initial browse.

To the LLM usage, I don't think it's a problem specifically in this case, but rather that the PR in question is a symptom of the broader problem of people throwing LLM-generated PRs at maintainers, like me, and asking us to dedicate time and effort to them. I was a bit snippy in closing it, which was maybe immature, but is a natural consequence of these kinds of extractive contributions wearing maintainers down.

I don't see any major technical flaws with the PR. But I'm not sure it's fundamentally right in the first place -- per the rest of this comment -- so being "technically sound" is wildly insufficient for this issue. The first thing is to convince maintainers that it's even a good idea and hammer out what behavior should be. Which I could be convinced about, and I am trying to be open minded.

So far, writing down the reasons that pip-tools' version is not generally a key piece of data for reproducibility has led me to believe more strongly that this is a misfeature. I think the only way to convince me right now is to cite a clear use-case in which this information would help.