Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pip cannot find setuptools while building a package

Errorsetuptools not available in build environment

Short 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.

  • Applies to pip 25, Python 3.12, Python 3.13, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.toml
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3An 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

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.toml

2Fix

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

Did this fix it?

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

Did this fix it?

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 setuptools

3Verify

The import now succeeds.

python -c "import setuptools, distutils; print('ok')"

Confirmed by docs.python.org

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.