sgl-project/sglang · error · SystemExit

Apple Metal shader compiler not found. Install a full Xcode

Error message

Apple Metal shader compiler not found. Install a full Xcode (not just Command Line Tools) so that `xcrun -sdk macosx metal` is available, then retry.

What it means

Beyond CLT, the Metal build needs the actual Metal shader compiler, verified by running `xcrun -sdk macosx metal --version`. Command Line Tools alone do not ship it, so the script demands a full Xcode install when the probe fails.

Source

Thrown at python/sglang/kernels/aot/setup_metal.py:49

    ("nanobind", "nanobind"),
]


def _ensure_toolchain():
    if sys.platform != "darwin" or platform.machine() != "arm64":
        raise SystemExit("setup_metal.py only supports macOS (Apple Silicon).")
    if shutil.which("c++") is None or shutil.which("xcrun") is None:
        raise SystemExit(
            "Apple toolchain not found. Install the Xcode Command Line Tools "
            "with `xcode-select --install` (or a full Xcode install) and retry."
        )
    try:
        subprocess.check_output(
            ["xcrun", "-sdk", "macosx", "metal", "--version"],
            stderr=subprocess.STDOUT,
        )
    except (subprocess.CalledProcessError, FileNotFoundError) as exc:
        raise SystemExit(
            "Apple Metal shader compiler not found. Install a full Xcode "
            "(not just Command Line Tools) so that `xcrun -sdk macosx metal` "
            "is available, then retry."
        ) from exc


def _ensure_build_requires():
    missing = []
    for import_name, pip_name in _BUILD_REQUIRES:
        try:
            importlib.import_module(import_name)
        except ImportError:
            missing.append(pip_name)
    if not missing:
        return
    print(
        f"[sgl-kernel:metal] installing build requirements: {missing}",
        flush=True,

View on GitHub (pinned to 0132848349)

Solutions

1. Install full Xcode from the App Store, launch it once to complete component installation, then retry
2. Confirm `xcrun -sdk macosx metal --version` succeeds in the build shell
3. Re-run sudo xcode-select -s /Applications/Xcode.app and accept the license with sudo xcodebuild -license accept

Example fix

# before
xcode-select --install
python setup_metal.py build_ext --inplace  # fails: Metal shader compiler not found
# after
# install full Xcode, then:
sudo xcode-select -s /Applications/Xcode.app
python setup_metal.py build_ext --inplace

subprocess.run(['xcrun','-sdk','macosx','metal','--version'], check=True, capture_output=True)

When it happens

Trigger: Running the Metal build with only Xcode CLT installed (no full Xcode), or with Xcode installed but its command-line components not yet finished installing/accepted.

Common situations: Minimal CI Macs with just CLT; freshly installed Xcode where first-launch license/components setup is incomplete; broken xcode-select developer dir.

Related errors

• Apple toolchain not found. Install the Xcode Command Line To
• {_METALLIB_NAME} not found next to the native Metal extensio
• setup_metal.py only supports macOS (Apple Silicon).
• metal_shader_sources is empty; nothing to compile
• metal shader source not found: {metal_src}

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/1d82acdb0b157649. Report an issue: GitHub.