Why can a PEP 517 build fail on an import that works in your active virtualenv?

## What isolation actually does When a frontend builds a source tree, PEP 517 says it should do so in an environment it controls. Concretely, pip creates a temporary environment, installs the `[build-system] requires` distributions into it, imports the backend *there*, and calls `build_wheel`. `python -m build` does the same. Two consequences follow, and both surprise people: 1. **Your activated environment is not on the build's path.** A package you installed by hand is not importable from the backend. Neither are your project's own runtime dependencies — `[project] dependencies` describe the *installed* package, and nothing installs them before the build. 2. **The build environment is fresh each time.** Everything in `requires` is resolved and installed again, so a cold build pays real wall-clock cost — on a cold wheel cache a modest project can spend forty-five seconds before the backend runs at all. Warm caches make that mostly disappear, but a locked-down CI image with no cache pays it on every job. ## The failure this produces The classic shape: a telemetry collector's build derives its version from source control using a backend plugin. The maintainer installed that plugin into the working environment long ago, so `python -m build` succeeded on their machine for a year. The plugin was never added to `requires`. A new CI runner builds from a clean checkout and the backend raises `ModuleNotFoundError` for the plugin — the build had silently depended on an *ordering* assumption, that something else would install the plugin before the build ran. Isolation did not break the build; it exposed that the declaration was incomplete. The same shape appears with a code generator, a compiler-facing helper, or a backend plugin that reads extra configuration. The fix is to declare it: ```toml [build-system] requires = ["setuptools>=77", "a-version-plugin>=8"] build-backend = "setuptools.build_meta" ``` If the requirement can only be known after inspecting the tree, that is exactly what the optional `get_requires_for_build_wheel` hook is for — the backend returns extra requirements and the frontend installs them into the same isolated environment. ## When turning isolation off is correct `pip install --no-build-isolation .` and `python -m build --no-isolation` are not hacks; they exist for real situations: * **Air-gapped or offline builds.** Isolation wants to *install* the requirements, which means reaching an index. With no network you must pre-install the build tools and disable isolation (or point pip at a local wheelhouse). * **A pre-release or locally patched build tool.** You want the backend you just built from a checkout, not the released one an isolated environment would fetch. * **Building against a specific already-installed library.** A source build of a compiled extension may need to link against the exact version of a library present in the environment; isolation would install a different one. * **Expensive build dependencies.** Where a build requirement itself has no wheel for the platform, resolving it from scratch every time can dominate the build. The cost of opting out is that you now own the build environment: every entry in `requires` must be installed by hand first, and the build silently uses whatever versions are there. In practice pair it with an explicit install step so the build is still reproducible: ```console $ python -m pip install "setuptools>=77" $ python -m pip install --no-build-isolation . ``` ## Controlling versions inside the isolated environment Isolation is not the same as pinning. Unless `requires` carries bounds, the isolated environment resolves the newest matching build tools each time, so a backend release can change your artifact without any change in your repository. Two levers: put honest lower bounds (and, for a release build you must reproduce, upper bounds) in `requires`; and apply constraints to the build environment — pip honours the `PIP_CONSTRAINT` environment variable when resolving build dependencies, which lets a platform team pin build tooling across many repositories without editing each `pyproject.toml`. ## Diagnosing it quickly When a build fails only in CI, ask three questions in order. Does the traceback come from *inside* the backend or from your own code being imported? A backend-side `ModuleNotFoundError` means a missing `requires` entry. Does the missing name appear anywhere in `requires`? If not, that is your answer. Does the build succeed with `--no-build-isolation` in an environment where the module is installed? If yes, the diagnosis is confirmed — and the *fix* is still to add the declaration, not to keep isolation off. Turning isolation off to make a red build green converts a clear, reproducible error into a machine-specific one, which is the single most common wrong response to this failure.