When is `python -m venv --system-site-packages` the right call, and what does it cost?

### What the flag actually does `python -m venv --system-site-packages .venv` differs from a plain creation in exactly one place: the line `include-system-site-packages` in `pyvenv.cfg` reads `true` instead of `false`. There is no other change to the directory, and because the interpreter reads that file at every startup, editing the line by hand on an existing environment has the same effect as creating it with the flag. That is a useful thing to know both because it makes the mechanism concrete and because it lets you check what a mystery environment on a server is doing without re-reading the deployment scripts. ### The effect on sys.path With the flag on, `site` appends the base installation's `site-packages` directory to `sys.path` *after* the environment's own. The order is the whole story: * A distribution installed into the environment wins, because its directory is searched first. * A distribution present only in the base installation is importable, because its directory is still on the path. * Installing into the environment therefore does not remove the base copy; it shadows it, leaving two versions on disk and first-match-wins resolution between them. That shadowing is where the surprises live. `pip list` inside the environment now reports base-installed distributions alongside your own; a freeze of that list is not a description of the environment you meant to build; and asking to uninstall a base-installed distribution from inside the environment is refused, because the files live outside it. ### When it is genuinely the right call * **A platform-provided binary package.** Some bindings — GUI toolkits, hardware or system-service libraries, vendor builds linked against a specific accelerator or driver stack — are shipped by the operating system's package manager or by the hardware vendor, and building an equivalent from an index is anywhere from painful to impossible. Letting the environment see the base installation is far less bad than abandoning environments altogether. * **A deliberately shared, expensive base layer.** On a constrained machine, or in a controlled image where a large compiled dependency is installed once and every environment is a thin overlay on top of it, the tradeoff can be a conscious one. * **A short-lived diagnostic environment.** When you want an isolated place to install one tool but still want everything the host already has, the flag saves a reinstall you were not going to keep. ### When it is the wrong call Anything you intend to reproduce. An environment created with the flag is not determined by its requirement pins alone — it is determined by the pins *plus the state of the machine*. Two hosts with the same pin file and different system packages produce different behaviour, and a routine upgrade of a system package changes an application's dependencies without anyone editing the application. That defeats the reason environments exist. It also breaks the mental model your teammates have: when someone reports that an import works on the server and fails in CI, this flag is a leading suspect, and it is invisible unless you read `pyvenv.cfg`. ### The practical stance Default to the isolated form; a plain `python -m venv .venv` is right nearly all the time. Where the flag is genuinely needed, make it explicit — record it in the command that builds the environment, note *which* base-provided package it exists for, and treat that package as a documented host requirement rather than an accident. If the only reason for reaching for it is that installing something from an index was slow or awkward, that is a packaging problem to solve, not a reason to give up isolation. One last detail worth carrying: since CPython 3.12 a newly created environment contains only `pip` — `setuptools` and `wheel` are no longer bootstrapped into it. Teams sometimes discover this while migrating an old build script, reach for `--system-site-packages` so the environment can see a system-installed `setuptools`, and quietly give up isolation to paper over a build-requirement declaration they should have written instead. ### Spotting it on a running system Because the setting lives in a file the interpreter reads at startup, you can always answer "is this environment isolated?" without trusting anyone's memory of how it was built. Print `pyvenv.cfg` from `sys.prefix` and read the boolean, or list the `site-packages` entries on `sys.path` and see whether one of them sits under `sys.base_prefix` rather than under `sys.prefix`. Both are one-liners, both work under a service manager where no shell was ever involved, and both belong in the first minute of investigating an import that behaves differently on two hosts.