pip "--no-build-isolation" Build Fails - Missing Backend in CI
By Daniel Zoghalchali·Latchkey
With --no-build-isolation, pip does not create a clean environment with the project’s [build-system] requires. Whatever the backend needs must already be installed - and when it is not, the build fails before compiling anything.
What this error means
A build run with --no-build-isolation fails with a ModuleNotFoundError for the build backend or one of its requirements (setuptools, hatchling, Cython, numpy). With isolation on, the same package builds because pip provisions those automatically.
pip output
ModuleNotFoundError: No module named 'hatchling'
ERROR: Could not build wheels for my-ext, which is required to install
pyproject.toml-based projects
Diagnose it: which Python, and which index?
A pip failure in CI is usually about the interpreter or the index rather than the package. Runners have several Pythons installed, and the one on PATH is not necessarily the one your virtualenv or your workflow selected.
Terminal
which -a python python3 pip pip3
python -c "import sys; print(sys.executable, sys.version)"
pip config list
pip debug --verbose 2>/dev/null | grep -i "compatible tags" | head -5
Common causes
Build requirements are not pre-installed
Disabling isolation tells pip to skip provisioning [build-system] requires. If the backend (and any build-time deps like Cython/numpy) are absent from the active environment, the build cannot import them.
Isolation disabled without a reason
Many CI scripts add --no-build-isolation to speed things up or work around a network restriction, then forget that they now own provisioning the build deps themselves.
How to fix it
Pre-install the backend and its build deps
Read the project’s [build-system] requires and install exactly those before the no-isolation build.
Terminal
python -m pip install --upgrade pip
pip install hatchling # plus any Cython/numpy the backend needs
pip install --no-build-isolation my-ext
Or just let pip isolate the build
Unless you have a specific reason, drop the flag and let pip provision the build environment from [build-system] requires.
Terminal
pip install my-ext # default build isolation provisions the backend
How to prevent it
Only disable build isolation when you pre-install every build requirement.
Mirror the project’s [build-system] requires in the pre-install step.
Prefer wheels in CI so no build runs at all.
Frequently asked questions
What causes pip "--no-build-isolation" build fails?
There are 2 common causes: build requirements are not pre-installed and isolation disabled without a reason. Disabling isolation tells pip to skip provisioning [build-system] requires.
How do I fix pip "--no-build-isolation" build fails?
There are 2 fixes depending on which cause you have: pre-install the backend and its build deps and or just let pip isolate the build. Work through them in order, since the first is the most common.
What does pip "--no-build-isolation" build fails actually mean?
A build run with --no-build-isolation fails with a ModuleNotFoundError for the build backend or one of its requirements (setuptools, hatchling, Cython, numpy).
How do I stop pip "--no-build-isolation" build fails happening again?
Only disable build isolation when you pre-install every build requirement. The prevention section lists 3 changes that keep it from recurring.
