PYTHONPATH

Where do PYTHONPATH entries land in sys.path?

Order is the whole story. CPython builds sys.path as: the script's own directory (or the current directory for -c and the REPL), then every PYTHONPATH entry in order, then the standard library, then site-packages. Imports take the first match walking that list — so PYTHONPATH entries outrank everything you installed with pip, and anything in them shadows same-named installed packages without a warning of any kind. A directory left on PYTHONPATH with a stale copy of your package means you can pip-install fixes forever and keep importing the old code.

# see the real search order, and where each module came from
python -c "import sys; print('\n'.join(sys.path))"
python -c "import requests; print(requests.__file__)"

Python 3.11 added an escape hatch aimed at exactly this class of bug: python -P (or PYTHONSAFEPATH=1) drops the implicit script-directory/cwd entry, so a file named token.py or secrets.py sitting next to your script stops shadowing the standard library.

What PYTHONPATH does not do

• It does not choose which Python runs — that's PATH (see the PATH page). A correct PYTHONPATH with the wrong interpreter is still the wrong interpreter.
• It does not install anything, resolve dependencies, or register entry points — modules become importable, nothing more. Console scripts defined in pyproject.toml stay missing.
• It is not virtualenv-aware. The variable leaks into every environment you activate, which defeats the isolation virtualenvs exist to provide.

The editable install replaced it — use that

The legitimate historical use of PYTHONPATH — "run my code from a checkout without installing it" — has a proper packaging answer: pip install -e . puts your project on sys.path through the import system, visibly (it shows in pip list), per-environment, and without shadowing risk. For test suites, pytest 7.0 added the pythonpath ini option so the old "export PYTHONPATH=src before running tests" ritual can live in committed config instead of fragile shell state:

# pyproject.toml
[tool.pytest.ini_options]
pythonpath = ["src"]

What survives as a good use of the variable is the one-off: PYTHONPATH=src python -m myapp.cli scoped to a single command, in a Makefile or a .env file loaded per-project. Scoped is the keyword — the failure mode is always the global export.

Why a global PYTHONPATH breaks other people's tools

Every Python process on the machine inherits it: the Python inside gcloud, aws-cli v1, dnf, Ansible, your editor's language server. A PYTHONPATH entry containing, say, an old six.py or a half-compatible yaml package gets imported by those tools in preference to their vendored versions, producing AttributeError crashes in software you never touched. This failure is common enough that Google's gcloud troubleshooting docs explicitly suggest unsetting PYTHONPATH. If a system Python tool crashes with an import-related traceback, run it with env -u PYTHONPATH before filing a bug. The broader catalog of Python's environment knobs — PYTHONHOME (far more destructive), PYTHONDONTWRITEBYTECODE, PYTHONUNBUFFERED — is in the Python environment variables guide.

Docker and CI: the acceptable exception

Inside a container image you control end to end, ENV PYTHONPATH=/app/src is defensible — there is exactly one Python, one app, and no neighboring tools to poison. Even there, copying the project in and running pip install --no-deps . in the build stage is barely more work and keeps the import mechanism standard. Where you see PYTHONPATH most in the wild is CI pipelines and Airflow/Spark deployments gluing zip artifacts onto the path; inherit those patterns knowingly rather than cargo-culting them into application code. Wiring per-environment values like this through compose files is covered in the docker-compose environment variables guide.