pip cannot find setuptools while building a package
setuptools not available in build environmentShort answer
pip builds source packages in a clean, isolated environment and installs only what the package lists under build-system requires. setuptools goes missing when that list is absent or wrong, when you turned isolation off with --no-build-isolation, or when a Python 3.12+ venv no longer ships it. Fix the list, or install setuptools first.
Fix it fast
1Find out which cause you have
Find out whether the package declares its build tools, and whether your pip command switched isolation off.
pip --version env | grep -i PIP_NO_BUILD_ISOLATION grep -A3 "build-system" pyproject.toml2Match what you see, then jump to its fix
- 1
The failing project is your own, or a vendored one, and pyproject.toml is missing the [build-system] table or lists no setuptoolsThe project has no usable [build-system] tableFix - 2
The command has --no-build-isolation, or PIP_NO_BUILD_ISOLATION is set in the Dockerfile or CIBuild isolation was turned off and setuptools is not installedFix - 3
An older setup.py, pkg_resources or distutils import fails in a fresh venv on Python 3.12 or newer, although it worked on 3.11A Python 3.12+ virtual environment does not contain setuptoolsFix
- 1
What does the error look like?
setuptools not available in build environment
Cause 1 of 3
The project has no usable [build-system] table
1Check
Open pyproject.toml. pip installs the packages named under requires into the isolated build environment. If setuptools is not listed there, the backend cannot import.
cat pyproject.toml2Fix
Add the table with setuptools and its backend. The Python Packaging guide says the table should always be present.
[build-system]
requires = ["setuptools >= 77.0.3"]
build-backend = "setuptools.build_meta"3Verify
Install the project again; the build step now gets its own copy of setuptools.
pip install .Confirmed by packaging.python.org
Cause 2 of 3
Build isolation was turned off and setuptools is not installed
1Check
With isolation off, pip does not install build dependencies for you. The pip reference says the PEP 518 build dependencies must already be installed in that case.
pip config list
python -m pip list | grep -i -E "setuptools|wheel"2Fix
Install the build tools into the same environment first, then run the install. Or remove the flag and let pip manage the build environment.
python -m pip install setuptools wheel
python -m pip install --no-build-isolation .3Verify
The second command finishes without the setuptools error.
python -c "import setuptools; print(setuptools.__version__)"Confirmed by pip.pypa.io
Cause 3 of 3
A Python 3.12+ virtual environment does not contain setuptools
1Check
Since Python 3.12, venv no longer pre-installs setuptools, and the standard library distutils is gone. Check which Python the venv uses.
python --version
python -c "import setuptools"2Fix
Install setuptools inside the activated environment. This is the step the Python 3.12 release notes give.
source .venv/bin/activate
pip install setuptools3Verify
The import now succeeds.
python -c "import setuptools, distutils; print('ok')"Confirmed by docs.python.org
How do I stop it coming back?
- Give every project of yours a pyproject.toml with a [build-system] table.
- In a Dockerfile, install the build tools in a separate early layer if you must use --no-build-isolation.
- Pin the Python version in the base image so a venv does not change behaviour after an image update.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix