sgl-project/sglang · error · SystemExit

Apple toolchain not found. Install the Xcode Command Line To

Error message

Apple toolchain not found. Install the Xcode Command Line Tools with `xcode-select --install` (or a full Xcode install) and retry.

What it means

setup_metal.py checks that the `c++` compiler and `xcrun` are on PATH before building. If either is missing, it exits with instructions to install the Xcode Command Line Tools, since the Metal extension cannot be compiled without them.

Source

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

import sys
import sysconfig
from pathlib import Path

root = Path(__file__).parent.resolve()


_BUILD_REQUIRES = [
    ("setuptools", "setuptools"),
    ("mlx", "mlx"),
    ("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 = []

View on GitHub (pinned to 0132848349)

Solutions

1. Run `xcode-select --install` (or install full Xcode) and retry
2. Verify with `xcode-select -p` that a valid developer dir is selected; run sudo xcode-select -r if broken
3. Check `which c++ xcrun` inside the same shell/venv used to build; fix PATH if either is missing

Example fix

# before
python setup_metal.py build_ext --inplace  # fails: Apple toolchain not found
# after
xcode-select --install
python setup_metal.py build_ext --inplace

assert shutil.which('c++') and shutil.which('xcrun')

When it happens

Trigger: Building the Metal extension on a Mac without Xcode CLT installed, or with a broken/PREPENDED PATH that hides /usr/bin/c++ or /usr/bin/xcrun (common in sanitized conda/venv environments).

Common situations: Fresh macOS machines or CI runners without CLT; environments where xcode-select points to an invalid developer dir; PATH stripped by a wrapper script.

Related errors

• Apple Metal shader compiler not found. Install a full Xcode
• {_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/d4cd5afabdda7d1c. Report an issue: GitHub.