The command line wins, then environment variables, then config files. Among config files, later ones override earlier ones: global, then user, then site, then any file named by PIP_CONFIG_FILE. So a stray user config or a CI variable can quietly send pip to an index you did not intend. Run pip config debug to see the truth.
The order, spelled out
The pip documentation gives a clear order for a setting such as the index URL:
- Command line options.
- Environment variables, named PIP_ followed by the upper case option name with dashes turned into underscores. By that rule the index URL option maps to PIP_INDEX_URL.
- Configuration files.
Config files are read in this order, and each file overrides values from the ones before it: global (system wide), user, site (per environment, inside the virtual environment), then the file named by PIP_CONFIG_FILE. Within a file, a section for a specific command, such as install, overrides the same setting under global.
Why small teams get surprised
Consider a laptop with a user config pointing at your mirror, and a project virtual environment with its own site config that nobody remembers creating. The site file wins over the user file. Now add a CI image where a base layer set an environment variable. That variable beats every file. Three places, three answers.
| Where it is set | Beats | Loses to |
|---|---|---|
| Command line | Everything | Nothing |
| Environment variable | All config files | Command line |
| Site config | User and global | Env and command line |
| User config | Global | Site, env, command line |
| Global config | Nothing | All others |
Find the effective setting
pip can print what it loaded.
pip config debug
pip config list
pip install --dry-run requests -v 2>&1 | grep -i "index"
The debug command lists the config file locations pip checks and which ones exist. Run it inside the same virtual environment and the same CI image that does the real install. A result from your laptop says little about CI.
A policy that keeps it boring
- Choose one place to set the index for CI, preferably an environment variable in the pipeline definition, since it is visible in review.
- Delete stray user and site config files in CI images, or set PIP_CONFIG_FILE to the null device to disable all config files, which the docs describe as possible.
- Pass the index on the command line in the one install step that matters most, such as a production image build.
- Add a CI step that runs the config debug command and fails if an unexpected index appears.
Do not use an extra index to add a second source and assume your internal one takes priority. pip pools candidates, which is the same hole that dependency confusion uses. A related post explains why an extra index undermines intake.
Where Safeguard fits
Safeguard's SBOM and dependency scanning records which Python packages and versions ended up in the build, so you can check the result even when the index path was unclear. A free scan is at gold.safeguard.sh/scan.
Quick check
Does a requirements file option override the environment variable?
pip's docs list command line options, then environment variables, then config files. Test your own setup with the debug command rather than assuming.
How do I turn off all config files for one run?
Set PIP_CONFIG_FILE to the null device, which the pip docs describe as disabling all config files.
Sources
Last reviewed: 19 October 2026.
