sgl-project/sglang · error · SystemExit

setup_metal.py only supports macOS (Apple Silicon).

Error message

setup_metal.py only supports macOS (Apple Silicon).

What it means

The Metal extension build script refuses to run anywhere other than macOS on Apple Silicon (darwin/arm64). Building the Metal/MLX kernels requires the Apple toolchain, so Linux/Intel platforms exit immediately.

Source

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

import shutil
import subprocess
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

View on GitHub (pinned to 0132848349)

Solutions

1. Skip/gate the Metal build on non-darwin-arm64 (check sys.platform and platform.machine() in your build script)
2. Run this build only on an Apple-Silicon macOS runner/machine
3. Ensure native arm64 Python is used (not Rosetta/x86_64) if you are on an M-series Mac

Example fix

# before
python setup_metal.py build_ext --inplace  # on Linux CI
# after
import sys, platform
if sys.platform == 'darwin' and platform.machine() == 'arm64':
    subprocess.run(['python', 'setup_metal.py', 'build_ext', '--inplace'])

import sys, platform
assert sys.platform=='darwin' and platform.machine()=='arm64'

def on_apple_silicon(): return sys.platform=='darwin' and platform.machine()=='arm64'

When it happens

Trigger: Running `python setup_metal.py ...` (or pip installing the aot package in a way that invokes it) on Linux, in an x86_64 Mac container/CI, or under Rosetta where platform.machine() reports x86_64.

Common situations: Shared CI pipelines that build all kernel variants on Linux runners; developers on Intel Macs; Docker containers with Linux images attempting to build the metal extra.

Related errors

• q/k/v dtypes must match
• Apple toolchain not found. Install the Xcode Command Line To
• Apple Metal shader compiler not found. Install a full Xcode
• 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/2c80f7fbde669685. Report an issue: GitHub.