pip loads config files in this order: global, user, then site (inside the active virtual environment), then any file named by PIP_CONFIG_FILE. Environment variables beat files, and command line flags beat both. Run pip config debug to see the exact paths and values on your machine.
The levels
| Level | Typical Unix location | Typical Windows location |
|---|---|---|
| Global | /etc/pip.conf or pip/pip.conf in the XDG config dirs | C:\ProgramData\pip\pip.ini |
| User | $HOME/.config/pip/pip.conf | %APPDATA%\pip\pip.ini |
| Site | $VIRTUAL_ENV/pip.conf | %VIRTUAL_ENV%\pip.ini |
macOS differs slightly, so use pip config debug instead of trusting a table. Each later file overrides values from earlier ones. Setting PIP_CONFIG_FILE to os.devnull disables all config files, which is handy for a clean test run.
Environment variables
Any option can be set with a PIP_ variable, with dashes turned into underscores. For example, PIP_TIMEOUT=60 equals --timeout=60. So PIP_INDEX_URL or PIP_EXTRA_INDEX_URL set in a shell profile changes where packages come from, with no config file involved.
Why this matters for hardening
The index URL decides where packages are downloaded from. If something changes it, installs can silently come from a different source. A config file you did not write, or an old environment variable, is the kind of thing worth finding before it finds you.
Steps
- Run
pip config debugand read every file it lists, noting which exist. - Run
pip config listto see effective values. - Search your environment for variables starting with
PIP_. - Check for
index-urlandextra-index-urllines you do not recognise. On extra indexes, read why pip extra-index-url is unsafe for private packages. - In each project, check whether a site level
pip.confsits in the virtual environment.
What a safe pip setup looks like
For most developers the goal is boring: one index, set in one place, that you can name from memory. If your company runs a private index, it should be set in the user or global file by your IT team, and projects should not override it with their own site file. If you find yourself adding a second index to fix a missing package, stop and read the note on extra indexes above before you commit that change.
When something behaves oddly, the quickest isolation test is a run with the config disabled, then one with only the environment variables you expect. Whichever run changes the result tells you which layer is responsible.
A note on virtual environments
The site config lives inside the active virtual environment, so a copied or shared environment can carry its own settings. Treat environments as disposable, as Python's own documentation describes them, and recreate rather than reuse one from an unknown source. See also do you need a Python virtual environment for security.
Safeguard scans Python dependencies and generates SBOMs, so you can see what a requirements file resolved to. A free scan is at gold.safeguard.sh/scan.
Quick check
Which wins, an environment variable or a config file?
The environment variable. pip's documentation orders precedence as command line options, then environment variables, then configuration files.
How do I run pip with no config at all?
Set PIP_CONFIG_FILE to os.devnull, which disables all configuration files, as pip documents.
Sources
Last reviewed: 19 October 2026.
