Error in requirements.txt dependency resolution

[mgeier]

When my requirements.txt doesn't directly mention a Sphinx version but contains a Python package (in my caseinsipid-sphinx-theme) that depends on a Sphinx version > 2, this is ignored and the version selected by RTD is used (1.8.5).

I'm getting this error message:

ERROR: After October 2020 you may experience errors when installing or updating packages. This is because pip will change the way that it resolves dependency conflicts.

We recommend you use --use-feature=2020-resolver to test your packages with the new resolver before it becomes the default.

insipid-sphinx-theme 0.1.0 requires sphinx>=3.1.2, but you'll have sphinx 1.8.5 which is incompatible.

I don't know whether the 2020-resolver feature has anything to do with this behavior or not (maybe this will work as expected in the future?).

Details

• Read the Docs project URL: https://mg.readthedocs.io/
• Build URL (if applicable): https://readthedocs.org/projects/mg/builds/11602670/

Expected Result

I expect the nested (transitive) dependencies from requirements.txt to overrule the package versions installed by RTD.

Actual Result

The Sphinx version requested by RTD (<2) is used instead of the one requested by a package in requirements.txt (>=3.1.2).

If I directly write Sphinx>=3.1.2 into requirements.txt it works as expected.

[stsewd]

I think the version is being set by another package https://github.com/spatialaudio/nbsphinx/blob/4c00890ed2a5bdf28981f87321bc11a1a2bfb3ef/setup.py#L22 maybe?

What about listing the insipid-sphinx-theme package first?

I don't know whether the 2020-resolver feature has anything to do with this behavior or not (maybe this will work as expected in the future?).

Not sure about that, is that something new introduced in the latest version of pip?

[mgeier]

Thanks for looking into this!

I think the version is being set by another package https://github.com/spatialaudio/nbsphinx/blob/4c00890ed2a5bdf28981f87321bc11a1a2bfb3ef/setup.py#L22 maybe?

I didn't think so, because it's sphinx>=1.8.

I'm quite sure the reason for the initial choice of version 1.8.5 is RTD, which requests sphinx<2 very early in the process.

The requirement sphinx>=1.8 is still fulfilled, but it would also be fulfilled with any higher version number.

What about listing the insipid-sphinx-theme package first?

I wouldn't expect that changing anything, but I tried it anyway (in a different project), and it works!

https://readthedocs.org/projects/jupyter-format/builds/11603286/

I've also tried it with the original project, and lo and behold, it work as well:

https://readthedocs.org/projects/mg/builds/11603351/

To be extra sure, I moved the insipid-sphinx-theme to the bottom of the requirements.txt, and the original error appears again:

https://readthedocs.org/projects/mg/builds/11603409/

But I still don't understand why that's the case ... do you have an idea?

I don't know whether the 2020-resolver feature has anything to do with this behavior or not (maybe this will work as expected in the future?).

Not sure about that, is that something new introduced in the latest version of pip?

No idea. It's the first time I've seen this message. But that doesn't mean much.

[stsewd]

But I still don't understand why that's the case ... do you have an idea?

I don't really have an explanation, just saw the first packages were defining the sphinx version from a lower point so maybe pip got confused? But that's unexpected for sure. I'll try to replicate this locally, maybe this is due to some options we set to pip?

[stsewd]

OK, I was able to replicate this locally

pip install --upgrade pip
pip install "Sphinx<2.0"
pip install -r test.txt

Where test.txt is

nbsphinx
ipykernel
sphinx-last-updated-by-git
insipid-sphinx-theme

And what I got was

ERROR: After October 2020 you may experience errors when installing or updating packages. This is because pip will change the way that it resolves dependency conflicts.

We recommend you use --use-feature=2020-resolver to test your packages with the new resolver before it becomes the default.

insipid-sphinx-theme 0.1.0 requires sphinx>=3.1.2, but you'll have sphinx 1.8.5 which is incompatible.

I think this is going to break some builds for sure... We'll need to take a look and see how this can be solved.

[stsewd]

But maybe this is a bug from pip since it works just fine changing the order (outside rtd)...

[mgeier]

Thanks for the exploration, that's very interesting.

I could reduce the test case to these two requirements:

sphinx-last-updated-by-git
insipid-sphinx-theme

sphinx-last-updated-by-git depends on sphinx>=1.8, insipid-sphinx-theme depends on sphinx>=3.1.2.

If I change the order it works as expected:

insipid-sphinx-theme
sphinx-last-updated-by-git

So far so good. Now I tried the command line option suggested in the error message:

pip install -r test.txt --use-feature=2020-resolver

And it works!

So it looks like the current pip version is broken and it will be fixed in October 2020.

It's probably not a good idea to use the new resolver by default on RTD, because it still seems to be under development.

I guess we'll just have to wait until October ... or for RTD to drop the sphinx<2 requirement ... whatever happens earlier ...

[mgeier]

PS: some more reading material:

https://pip.pypa.io/en/latest/user_guide/#changes-to-the-pip-dependency-resolver-in-20-2-2020

Here's an issue from 2013: pypa/pip#988.
It talks about the "first found wins" behavior, which is the culprit in this very issue here.

[stsewd]

Thanks for the links, so, we are planning to install sphinx<3 by default, but not matter the sphinx version we pin, pip will give that error on some circumstances.

This also means that, when you run a pip install command, pip only considers the packages you are installing in that command, and may break already-installed packages.

With that users won't have to worry about previous installed packages by rtd.

I think you may want to report this issue upstream, but not sure since it's already fixed in the new resolver 🤷‍♂️ and we are not so far from October at least if the world doesn't end.

[mgeier]

With that users won't have to worry about previous installed packages by rtd.

That's not quite true (currently), as our experiments above have shown.

The same requirements in test.txt lead to different Sphinx versions being installed, depending on the previously installed Sphinx version.

If sphinx<2 is requested in a first call to pip, the second call to pip will not change the Sphinx version.

But I think this problem will go away in October.

I think you may want to report this issue upstream

AFAIU, this issue is known at least since 2013, I don't think I have anything to add to the error description.

I think I'll just wait a few months ...

[stsewd]

I'm closing this since it's a pip issue and hopefully will be fixed in the next month. We will always install some libraries before the ones the user installs, as we require some for our features to work. Feel free to ask to reopen if the problem doesn't go away when the new pip resolver is used by default.

[mgeier]

Just a quick confirmation: this issue indeed seems to be fixed, the original problem doesn't appear anymore!