PIP_CONFIG_FILE overrides other configs in conflict with documentation

[dalebrydon]

Description

When PIP_CONFIG_FILE is set, values in that file override other files. However in the documentation it states:

Additionally, the environment variable PIP_CONFIG_FILE can be used to specify a configuration file that’s loaded first, and whose values are overridden by the values set in the aforementioned files.

I presume that the intended functionality is what is described in the documentation, especially since there is a comment to that effect in Configuration.iter_config_files. (Namely, # environment variables have the lowest priority.) However, given the length of time things have been this way, maybe the docs are what's wrong.

The actual functionality is determined by override order, where kinds.ENV is the second highest priority. I think having the order specified in two different places is the ultimate source of the bug.

Happy to submit a PR once there's some clarity on what the right way to fix it is.

Expected behavior

No response

pip version

all

Python version

3

OS

any

How to Reproduce

Have any (global, user, site) pip.conf in a standard path and run > PIP_CONFIG_FILE=/path/to/any/other/pip.conf pip config debug

Output

No response

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[pradyunsg]

Changing the docs to match reality seems like the right thing to do here. Thanks for catching and flagging this.

[dalebrydon]

I'll try to submit a PR fixing the docs later this week. I think that having the environment variable be the final authority is pretty intuitive and consistent with how Pip and other programs use env vars.

That being said I was pulling for this not being the case, since this leaves no mechanism to have a default file that a user can override without root. Maybe I'll open a separate issue to look into creating such a mechanism.

[ChrisBarker-NOAA]

Another note about docs for pip configuration:

as I read:
https://pip.pypa.io/en/stable/topics/configuration/#configuration-files

There are four possible places for config files (OS-X example)

Global: /Library/Application Support/pip/pip.conf

User:
$HOME/Library/Application Support/pip/pip.conf if directory $HOME/Library/Application Support/pip exists else $HOME/.config/pip/pip.conf

The legacy “per-user” configuration file is also loaded, if it exists: $HOME/.pip/pip.conf

Site:
$VIRTUAL_ENV/pip.conf

However, there seems to be no way to specify pip configuration in the base Python -- which would be very ueful for, e.g. conda environments.

However, in the code:
pip/[_internal]
(https://github.com/pypa/pip/tree/56e5fa3c0fd0544e7b5b9b89d9d7854b82d51242/src/pip/_internal)/configuration.py

There is code to look in sys.prefix:

    base_config_file = os.path.join(sys.base_prefix, CONFIG_BASENAME)
    site_config_file = os.path.join(sys.prefix, CONFIG_BASENAME)

Hmm -- looking now, that was added by @pelson on Oct 6, 2022 -- so new -- but there have been three releases since then -- so I think this needs to be added to the docs.

[pradyunsg]

However, there seems to be no way to specify pip configuration in the base Python -- which would be very ueful for, e.g. conda environments.

That's #9752.

https://pip.pypa.io/en/latest/topics/configuration/#configuration-files (note latest vs stable, and the docs needs a fix in the version numbers)

[pelson]

In response to @ChrisBarker-NOAA (hi Chris! 👋):

Yes, the change was made in #11487 to include the config from the base environment. The documentation was updated to reflect this change, but it hasn't yet made it into a release (merged in January) - all things being equal, it will be in pip 23.1.

It doesn't help with conda environments though, since they are not virtual environments. I don't think you would want pip config to bleed between conda environments in general, and if that is really what you want, then you could achieve that with the proposals being made in conda/ceps#45 (to be seen if that proceeds).

---

At a certain point I wished to be able to override the pip config precedence (think it was discussed in the linked PR), but it was rejected for its complexity and potential impact on system administrators ability to control pip. Despite this, the way things are today means that as a user you have more power to control your pip environment than a sys-admin does (I like this 😉).

👍 to updating the docs to reflect the current behaviour that the environment file is loaded last.

[ChrisBarker-NOAA]

It doesn't help with conda environments though, since they are not virtual environments. I don't think you would want pip config to bleed between conda environments in general,

I agree -- but I think that all the previous configuration options are outside conda environments -- and that this new feature would allow you to have a configuration specific to a particular environment, which is what I'm looking for.

and if that is really what you want, then you could achieve that with the proposals being made in conda/ceps#45 (to be seen if that proceeds).

I'm not sure that that would do what I'm looking for, but in any case, this is a topic for conda / conda-forge. pip seems to be in good shape with regard to this once the new docs get published.