Why is pip using an index I did not set? Check config precedence

Pip reads several configuration files and environment variables, and the winner follows a fixed order: command line options beat environment variables, which beat config files. Run pip config list to see the active values, and pip config debug to see which files were loaded. Surprise indexes usually come from a forgotten file or variable.

The precedence rules

The pip configuration guide sets out two layers.

Between sources: command line options override environment variables, which override the values in a configuration file.

Between config files: when several are found, pip combines them in this order, and each file read overrides values from the previous ones: Global, then User, then Site, then the file named by the PIP_CONFIG_FILE variable, if given.

Inside a file, a section for a specific command overrides the global section. A setting under the install section beats the same setting under global.

The environment variable names follow a rule from the guide: take the long option name, uppercase it, replace dashes with underscores, and add the PIP_ prefix. So the index URL option corresponds to PIP_INDEX_URL.

How to see what is active

Two subcommands from the pip config reference answer most questions. The list subcommand shows the active configuration. The debug subcommand lists the configuration files and the values defined under each.

python -m pip config list
python -m pip config debug
env | grep '^PIP_'

The third line matters because environment variables are not shown in a file listing. CI systems and base images often set them.

Common causes of a surprise index

1. A global file baked into a base image years ago.
2. A user file left on a shared build runner.
3. A PIP_INDEX_URL or PIP_EXTRA_INDEX_URL set in the CI project settings.
4. An environment file from a virtual environment, which the config reference calls the site file.

Any of these can add or replace an index. This is also why a second index is risky. See why extra-index-url is unsafe for private packages and where to set pip index-url so developers cannot skip it.

Making CI predictable

Two options from the pip reference help.

• The isolated option runs pip in isolated mode, ignoring environment variables and user configuration. It gives you a clean baseline, then you pass exactly the flags you want.
• Setting PIP_CONFIG_FILE to the null device disables loading of all configuration files, according to the configuration guide.

A clean approach is to run isolated in CI and pass the index, hash and binary options explicitly in the script, where code review can see them.

An audit you can run today

Pick three build runners and one developer laptop. On each, run the three commands above and save the output. Compare the index lines. If any differ, find out why. The difference is where a build will someday pull a package you did not intend.

Safeguard's dependency scanning shows what each build actually resolved, which is a useful cross check when two environments behave differently. A free scan is available at gold.safeguard.sh/scan.

Quick check

Sources

• pip documentation, Configuration
• pip documentation, pip config
• pip documentation, pip general options

Last reviewed: 19 October 2026.