How does CPython assemble sys.path when the interpreter starts?

## sys.path is a list, and its order is the whole story `sys.path` is nothing more exotic than a list of strings that the import machinery walks front to back when it needs to locate a top-level module or package. Everything interesting about it is *how it gets populated* and *in what order*, because the first match wins and later entries never get a say. ### 1. The leading entry — where you started from The first entry is decided by how the interpreter was invoked: * `python app.py` — the directory containing `app.py`. Since 3.11 CPython inserts it as an absolute path, so a later change of working directory cannot silently change its meaning. * The REPL, and `python -c "..."` — `''`, an empty string meaning "the current working directory, resolved at the moment of each import". * Reading a program from standard input behaves like the interactive case. This entry is the reason your own modules are importable without installing anything, and equally the reason a local file can shadow a standard-library name. You can switch it off. Since 3.11, the `-P` flag and the `PYTHONSAFEPATH=1` environment variable both tell CPython not to prepend that leading entry at all, which is a useful hardening step for a process that should import only what has been installed for it. ### 2. PYTHONPATH Next come the directories listed in the `PYTHONPATH` environment variable, split on the platform's path separator. They sit ahead of the standard library, which is what makes `PYTHONPATH` powerful and dangerous in equal measure: an entry there can shadow standard-library and installed code for every process that inherits the variable. `-E` makes the interpreter ignore `PYTHON*` variables entirely, and `-I` (isolated mode) implies `-E` plus dropping the user site directory. ### 3. The interpreter's own directories Then come the installation-dependent locations derived from the interpreter's prefix: a zip archive of the standard library if one is present, the standard-library directory itself, and the directory holding compiled extension modules. `PYTHONHOME` overrides the prefix used to compute these, which is almost always a mistake outside of embedding scenarios — pointing it at a mismatched installation is a reliable way to produce an interpreter that cannot find its own standard library. ### 4. site-packages, appended by the site module Unless the interpreter was started with `-S`, CPython imports the `site` module at the end of startup, and `site` appends the third-party locations: the per-user site directory (skipped with `-s`, or `PYTHONNOUSERSITE`, and reported by `site.ENABLE_USER_SITE`) and the environment's site-packages, which `site.getsitepackages()` will report back to you. While scanning those directories, `site` processes every `.pth` file it finds there. The rule is small and worth knowing exactly: each line that names a directory is appended to `sys.path`; each line that begins with `import ` is *executed* as Python code. That second rule is not a curiosity — it is the hook that editable installs and several path-manipulating tools rely on, and it means anything writable in site-packages can run code at every interpreter start. A virtual environment is not a separate mechanism: its marker file makes the interpreter compute a different prefix, so `site` appends the environment's site-packages rather than the base installation's, and the ordering above is unchanged. ### After startup Once startup is over, `sys.path` is an ordinary mutable list. `sys.path.append(...)` and `sys.path.insert(0, ...)` work, and plenty of code does exactly that to make a sibling directory importable. Treat it as a smell: it is invisible to tooling, it is order-sensitive, it runs after some imports have already resolved, and it is the usual root cause of one file being loaded twice under two names. Installing the project — including as an editable install during development — expresses the same intent in a way every process and every tool agrees on. Two caching details matter when you *do* manipulate the path or the filesystem at runtime. The import system caches a finder per path entry in `sys.path_importer_cache`, and directory listings are cached too. Create a module file after the containing directory has already been searched and the import can fail on stale state; `importlib.invalidate_caches()` is the supported way to force a re-scan. ### Reading the real thing The fastest way to answer "why did it import *that*" is to print the path itself. `python -c "import sys; print(*sys.path, sep='\n')"` shows the assembled order for that exact invocation, and comparing the output between two invocations — with and without a flag, inside and outside an environment — explains almost every path mystery without guesswork.