{"record":{"id":"321f6964c96d2bd0","repo":"python/cpython","slug":"cannot-locate-working-compiler","errorCode":null,"errorMessage":"Cannot locate working compiler","messagePattern":"Cannot locate working compiler","errorType":"exception","errorClass":"SystemError","httpStatus":null,"severity":"error","filePath":"Lib/_osx_support.py","lineNumber":245,"sourceCode":"        # to find an uninstalled clang (within a selected Xcode).\n\n        # NOTE: Cannot use subprocess here because of bootstrap\n        # issues when building Python itself (and os.popen is\n        # implemented on top of subprocess and is therefore not\n        # usable as well)\n\n        cc = _find_build_tool('clang')\n\n    elif os.path.basename(cc).startswith('gcc'):\n        # Compiler is GCC, check if it is LLVM-GCC\n        data = _read_output(\"'%s' --version\"\n                             % (cc.replace(\"'\", \"'\\\"'\\\"'\"),))\n        if data and 'llvm-gcc' in data:\n            # Found LLVM-GCC, fall back to clang\n            cc = _find_build_tool('clang')\n\n    if not cc:\n        raise SystemError(\n               \"Cannot locate working compiler\")\n\n    if cc != oldcc:\n        # Found a replacement compiler.\n        # Modify config vars using new compiler, if not already explicitly\n        # overridden by an env variable, preserving additional arguments.\n        for cv in _COMPILER_CONFIG_VARS:\n            if cv in _config_vars and cv not in os.environ:\n                cv_split = _config_vars[cv].split()\n                cv_split[0] = cc if cv != 'CXX' else cc + '++'\n                _save_modified_value(_config_vars, cv, ' '.join(cv_split))\n\n    return _config_vars\n\n\ndef _remove_universal_flags(_config_vars):\n    \"\"\"Remove all universal build arguments from config vars\"\"\"\n","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/_osx_support.py#L227-L263","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install/repair the Command Line Tools: `xcode-select --install` (or `xcode-select --switch /Library/Developer/CommandLineTools`)","Verify the toolchain resolves: `xcrun --find clang && clang --version`","Unset stale overrides: `unset CC CXX CFLAGS` (and check ARCHFLAGS/CPATH aren't pinning a dead toolchain)","If Xcode is installed: accept the license with `sudo xcodebuild -license accept` and ensure `xcode-select -p` prints a valid path","Reinstall CLT if xcrun still fails: `sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install`"],"exampleFix":"# before (broken env pointing at a removed Homebrew gcc)\nexport CC=/usr/local/bin/gcc-12\npip install .   # SystemError: Cannot locate working compiler\n\n# after\nunset CC CXX\nxcode-select --install\npip install .","handlingStrategy":"validation","validationCode":"import shutil, subprocess\n\ndef compiler_available() -> bool:\n    try:\n        path = subprocess.run(['xcrun', '--find', 'clang'], capture_output=True, text=True, timeout=10)\n        if path.returncode == 0:\n            return True\n    except (FileNotFoundError, subprocess.TimeoutExpired):\n        pass\n    return shutil.which('clang') is not None\n\n# run before building extensions on macOS\nif sys.platform == 'darwin' and not compiler_available():\n    raise SystemExit('Install Xcode Command Line Tools: xcode-select --install')","typeGuard":null,"tryCatchPattern":"import sys\nfrom setuptools import setup\n\ntry:\n    setup(...)\nexcept SystemError as e:\n    if 'Cannot locate working compiler' in str(e):\n        raise SystemExit('No working compiler: run `xcode-select --install` and unset CC/CXX') from e\n    raise","preventionTips":["Provision Xcode Command Line Tools in CI/Dockerfiles before any pip install that builds C extensions","Do not hardcode CC/CXX to Homebrew paths in shell profiles; let macOS resolve clang via xcrun","After macOS/Xcode upgrades, run `clang --version` once before builds","Cache the compiler check at the top of build scripts so failures surface before long dependency installs"],"tags":["macos","compiler","build","xcode","clang","environment"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}