python/cpython · error · SystemError

Cannot locate working compiler

Error message

Cannot locate working compiler

What it means

Raised by _osx_support.compiler_fixup, CPython's macOS build-support helper used by distutils/setuptools when customizing compiler config vars. The routine takes the configured CC, tries to verify it, and falls back to searching for clang (also converting an llvm-gcc CC to clang). If no working compiler can be located by _find_build_tool, it gives up with SystemError('Cannot locate working compiler'). In practice this means the machine has no usable clang/Xcode command-line toolchain where the helper looks (xcrun, PATH).

Source

Thrown at Lib/_osx_support.py:245

        # to find an uninstalled clang (within a selected Xcode).

        # NOTE: Cannot use subprocess here because of bootstrap
        # issues when building Python itself (and os.popen is
        # implemented on top of subprocess and is therefore not
        # usable as well)

        cc = _find_build_tool('clang')

    elif os.path.basename(cc).startswith('gcc'):
        # Compiler is GCC, check if it is LLVM-GCC
        data = _read_output("'%s' --version"
                             % (cc.replace("'", "'\"'\"'"),))
        if data and 'llvm-gcc' in data:
            # Found LLVM-GCC, fall back to clang
            cc = _find_build_tool('clang')

    if not cc:
        raise SystemError(
               "Cannot locate working compiler")

    if cc != oldcc:
        # Found a replacement compiler.
        # Modify config vars using new compiler, if not already explicitly
        # overridden by an env variable, preserving additional arguments.
        for cv in _COMPILER_CONFIG_VARS:
            if cv in _config_vars and cv not in os.environ:
                cv_split = _config_vars[cv].split()
                cv_split[0] = cc if cv != 'CXX' else cc + '++'
                _save_modified_value(_config_vars, cv, ' '.join(cv_split))

    return _config_vars


def _remove_universal_flags(_config_vars):
    """Remove all universal build arguments from config vars"""

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Install/repair the Command Line Tools: `xcode-select --install` (or `xcode-select --switch /Library/Developer/CommandLineTools`)
2. Verify the toolchain resolves: `xcrun --find clang && clang --version`
3. Unset stale overrides: `unset CC CXX CFLAGS` (and check ARCHFLAGS/CPATH aren't pinning a dead toolchain)
4. If Xcode is installed: accept the license with `sudo xcodebuild -license accept` and ensure `xcode-select -p` prints a valid path
5. Reinstall CLT if xcrun still fails: `sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install`

Example fix

# before (broken env pointing at a removed Homebrew gcc)
export CC=/usr/local/bin/gcc-12
pip install .   # SystemError: Cannot locate working compiler

# after
unset CC CXX
xcode-select --install
pip install .

import shutil, subprocess

def compiler_available() -> bool:
    try:
        path = subprocess.run(['xcrun', '--find', 'clang'], capture_output=True, text=True, timeout=10)
        if path.returncode == 0:
            return True
    except (FileNotFoundError, subprocess.TimeoutExpired):
        pass
    return shutil.which('clang') is not None

# run before building extensions on macOS
if sys.platform == 'darwin' and not compiler_available():
    raise SystemExit('Install Xcode Command Line Tools: xcode-select --install')

import sys
from setuptools import setup

try:
    setup(...)
except SystemError as e:
    if 'Cannot locate working compiler' in str(e):
        raise SystemExit('No working compiler: run `xcode-select --install` and unset CC/CXX') from e
    raise

When it happens

Trigger: Compiling C extensions on macOS (pip install of an sdist, python setup.py build_ext, setuptools commands that call sysconfig/distutils customization) when CC names a nonexistent or broken compiler AND _find_build_tool('clang') fails — e.g. CC=/usr/local/bin/gcc-12 from a removed Homebrew install, or xcrun cannot find clang because Command Line Tools are absent.

Common situations: Fresh Mac without `xcode-select --install` run; Xcode upgraded but license not accepted; DEVELOPER_DIR or DEVELOPER_DIR_DIR pointing at a stale Xcode path; CC/CXX exported in shell profile or CI env pointing to a deleted compiler; minimal CI/Docker macOS images without CLT; mixing Homebrew gcc-<n> aliases after a brew upgrade.

Related errors

• Don't know machine value for archs=%r
• Python ssl module is not available
• terminal doesn't have the required {cap} capability
• stdlib ssl module not available
• posix_spawnattr_setbinpref failed to copy\n

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/321f6964c96d2bd0. Report an issue: GitHub.