Turn on pip's require-virtualenv setting, either as a flag or through the PIP_REQUIRE_VIRTUALENV environment variable. Pip then exits with an error unless it is running inside a virtual environment. A mistaken install can no longer change the system Python, and a bad package stays inside a folder you can delete.
The setting
The pip general options reference describes it in one sentence: allow pip to only run in a virtual environment, and exit with an error otherwise. It lists two environment variable names, PIP_REQUIRE_VIRTUALENV and PIP_REQUIRE_VENV.
You can set it in three places, matching the precedence rules from the pip configuration guide.
# one command
python -m pip install --require-virtualenv requests
# a shell profile
export PIP_REQUIRE_VIRTUALENV=true
# a pip config file, applied to every command
python -m pip config set global.require-virtualenv true
The config file route uses the global prefix described in the pip config reference, which affects any command. Remember that environment variables override config files, so a user could set the variable to a false value. For strict control, set it where users cannot easily undo it, such as a managed image.
Why it matters
Installing into the global interpreter has a wider reach than people expect.
- Shared state. Packages in the global site directory are visible to every script run with that interpreter, including system tools on some operating systems.
- Hard cleanup. Removing a bad package from a shared environment can leave dependencies behind and break other things.
- Mixed trust. One developer's experiment becomes everyone's import.
- Privilege. Global installs often need elevated rights, which is the wrong time to run unreviewed install code.
A virtual environment limits the blast radius. Delete the folder and you are back to a clean state. See do you need a virtual environment for security and why pip says externally managed environment.
Where to enforce it
| Place | Effect |
|---|---|
| Developer shell profile | Stops accidental global installs on laptops |
| Base image for CI | Makes jobs fail early when a script forgets to activate |
| Container image | Forces a deliberate decision about the environment |
| Team onboarding doc | Sets the habit |
In a container, a global install can be the intended design, since the container is the isolation boundary. In that case, do not set the variable, and instead keep the image small and the install step hashed.
A rollout plan
- Set the variable in CI first. Failures show you scripts that rely on global installs.
- Fix those scripts to create and use a virtual environment.
- Roll it out to developer machines through the shell profile or a managed config.
- Check with pip config list that the setting is active.
Limits
The setting does not make installs safe. A package installed into a virtual environment can still run code when you import it. It only controls where installs go. Combine it with hash checking and review of new dependencies.
Safeguard's dependency scanning shows which packages ended up in a project's environment, so unexpected additions are easier to spot. A free scan is available at gold.safeguard.sh/scan.
Quick check
Does require-virtualenv block installs inside a venv?
No. It only blocks pip when it is not running in a virtual environment.
Can a user override the setting?
Possibly. Environment variables and command line options take precedence over config files. Set it in a managed place for stricter control.
Sources
- pip documentation, pip general options
- pip documentation, Configuration
- pip documentation, pip config
Last reviewed: 19 October 2026.
