PythonProductivityTips

The One Line That Saved Me From Python Dependency Hell

I spent years accidentally polluting my global Python environment. One environment variable fixed it permanently — and I only found it by accident.

2 min read

Add this to your .zshrc or .bashrc:

export PIP_REQUIRE_VIRTUALENV=true

That’s it. That’s the post.

Okay, a bit more context.

If you’ve used Python for any length of time you’ve probably done this at least once:

pip install requests

No virtual environment active. Packages go straight into your global Python installation. A few weeks later you’re debugging a bizarre import error, or a tool breaks because something updated something else, and you spend an hour tracing it back to that one pip install you ran without thinking.

PIP_REQUIRE_VIRTUALENV=true makes pip refuse to run outside a virtual environment. Not a warning — a hard stop:

ERROR: Could not find an activated virtualenv (required).

Now you have to activate your environment before installing anything. The habit gets forced.

How I found this

I didn’t find it in the pip docs. I stumbled across it in someone’s dotfiles on GitHub while looking for something completely unrelated. I’ve been using pip for years and had no idea this variable existed.

Looking back at the docs, it is technically documented — buried in a configuration reference page I’d never had reason to read. The kind of thing you only find if you’re already looking for it.

The workflow it enables

Once you’ve set this, the full workflow becomes:

cd my-project
python -m venv .venv      # or: uv venv
source .venv/bin/activate
pip install -r requirements.txt

Or with uv, which I’ve switched to for almost everything:

cd my-project
uv sync

uv creates and manages the virtual environment for you, so the restriction mostly applies when you’re working on older projects or running quick one-off installs.

What if you actually need to install globally?

Occasionally you do want to install something globally — pipx itself, for example. You can bypass the restriction for a single command:

PIP_REQUIRE_VIRTUALENV=false pip install pipx

Or just use pipx for global tools, which isolates each one in its own virtualenv anyway. That’s the right tool for CLI utilities you want available system-wide.

The broader principle

The best productivity improvements are the ones that make the wrong thing harder to do than the right thing. You don’t need willpower; you need friction in the right place.

One line in your shell config, and a whole category of debugging sessions disappears.