Compilation vs --upgrade produce different comments

[feanil]

Environment Versions

1. OS Type: Ubuntu 24.04.3 LTS
2. Python version: Python 3.11.13
3. pip version: 25.3
4. pip-tools version: 7.5.2

Steps to replicate

1. Run pip-compile --upgrade doc.in.txt
2. Run pip-compile doc.in.txt
3. Notice that nothing changes in the output except for the comment for roman-numerals which seems to resolve differently.

Expected result

I was expected the output to not change between step 1 and step 2

Actual result

There is a diff for re-compiling the requirements even though nothing has changed.i

───────────────────────────────┐
• doc.txt:29: pygments==2.19.2 │
───────────────────────────────┘
 29 ⋮ 29 │requests==2.32.5
 30 ⋮ 30 │    # via sphinx
 31 ⋮ 31 │roman-numerals==4.1.0
 32 ⋮    │    # via                                                                                                                                            
 33 ⋮    │    #   roman-numerals-py                                                                                                                            
 34 ⋮    │    #   sphinx                                                                                                                                       
    ⋮ 32 │    # via roman-numerals-py                                                                                                                          
 35 ⋮ 33 │roman-numerals-py==4.1.0
 36 ⋮ 34 │    # via sphinx
 37 ⋮ 35 │snowballstemmer==3.0.1

doc.in.txt

[sirosen]

I wasn't clear on what the reproducer here was exactly, but I've just put in a few minutes and gotten a similar result.
All that's needed:

# requirements.in
sphinx
sphinx-design

and then run

pip-compile
cp requirements.txt old.requirements.txt
pip-compile
diff requirements.txt old.requirements.txt

I have a pretty good guess as to how/why this happens.
When updating packages with an existing set of pins, rather than doing fresh resolution, as with --upgrade, the parameters for package resolution are different.

All of those pins in doc.txt (or requirements.txt in my example) are fed into package resolution. What you're seeing is something like the difference between pip install sphinx sphinx-design vs pip install sphinx sphinx-design requests==2.32.5 roman-numerals==4.1.0 roman-numerals-py=4.1.0 .... The resolution is very likely to behave differently in these two different cases.

However, if you were to repeatedly run it, always with or without --upgrade, you would see the output converge. It won't keep on changing because it's getting the same input.

---

I hope that at least explains why this happens. I'm really not sure how we could avoid it offhand, but I'm open to ideas. Or we could document it as "this is how it behaves".

[feanil]

Thanks for the explanation, that makes sense. For context, we were using pip compile without the --upgrade flag to verify that all output files are "coherent". Mostly to make sure that manual edits have not occured that would fail normal dependency resolution. I'm not sure if there is another way to do that?

---

For the underlying issue, I'm not sure how it works at the moment, so I don't think I could provide more input. I'm surprised that in doing the resolution equivalent to pip install sphinx sphinx-design, pip-compile wouldn't add the dependency of subdependencies to a list as it's building the dependency tree.

[sirosen]

I'm surprised that in doing the resolution equivalent to pip install sphinx sphinx-design, pip-compile wouldn't add the dependency of subdependencies to a list as it's building the dependency tree.

I admit that I'm surprised by the difference in results that you get, myself. But I know that we're asking the resolver to do different work in the two different invocations, so it makes some sense to me that "the results could be different".
i.e. I have a high level grasp of this, but couldn't tell you why this exact difference comes out.

I think you'll have a variety of workarounds possible, but no perfect solution. I have two ideas which I came up with.

Strip off the comments, compare insensitively

You could run with --no-annotate, something like this

grep -v '^\s*#' requirements.txt > bare.txt
cp bare.txt bare-update.txt
pip-compile --no-annotate -o bare-update.txt
cmp bare.txt bare-update.txt

Then you at least can ensure that nobody is manually modifying the dependency data. You'd have no control over the comments, since the point of --no-annotate is to strip those out.

Use constraints and remove the old output file, thus keeping inputs the same

Another idea which occurred is that you could intentionally remove all of those extra pins from the resolver inputs, and use them as constraints instead. It needs to be done with PIP_CONSTRAINT because using -c results in it being included in the annotation comments.

Something like this:

pip-compile -q --strip-extras doc.in -o doc.txt
mv doc.txt old.doc.txt
PIP_CONSTRAINT=old.doc.txt pip-compile -q --strip-extras doc.in -o doc.txt
diff doc.txt old.doc.txt

When I try that, it works as a workaround. Resolution is still impacted by setting constraints, but not as much as changing the set of packages which are requested, if that makes sense.

Notably, this moves doc.txt, so that pip-compile won't see it as its output/destination. You can also do things like -o - but then the header comment changes.

[sirosen]

I don't see this as a bug per se and although it's hard to understand intuitively, I'm not sure there's more we can do (within reason) to make the two invocations behave more identically. As such, I'm closing only because I don't see anything actionable here.