{"record":{"id":"f3330bcd52e2414b","repo":"sgl-project/sglang","slug":"sglang-use-mlx-requires-stable-torch-2-13-x-and-ml","errorCode":null,"errorMessage":"SGLANG_USE_MLX requires stable Torch 2.13.x and MLX >= 0.32.0, but MLX is not installed; reinstall with the srt_mps extra","messagePattern":"SGLANG_USE_MLX requires stable Torch 2\\.13\\.x and MLX >= 0\\.32\\.0, but MLX is not installed; reinstall with the srt_mps extra","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/hardware_backend/mlx/runtime.py","lineNumber":35,"sourceCode":"    except InvalidVersion:\n        return False\n    return not version.is_prerelease and (version.major, version.minor) == series\n\n\ndef _is_stable_at_least(raw_version: object, minimum: Version) -> bool:\n    try:\n        version = Version(str(raw_version))\n    except InvalidVersion:\n        return False\n    return not version.is_prerelease and version >= minimum\n\n\n@lru_cache(maxsize=1)\ndef _validate_runtime() -> None:\n    try:\n        import mlx.core as mx\n    except ImportError:\n        raise RuntimeError(\n            \"SGLANG_USE_MLX requires stable Torch 2.13.x and MLX >= 0.32.0, \"\n            \"but MLX is not installed; reinstall with \"\n            \"the srt_mps extra\"\n        ) from None\n    mlx_version = getattr(mx, \"__version__\", None)\n    torch_version = getattr(torch, \"__version__\", None)\n    if not _is_stable_series(\n        torch_version, _SUPPORTED_TORCH_SERIES\n    ) or not _is_stable_at_least(mlx_version, _MIN_MLX_VERSION):\n        raise RuntimeError(\n            \"SGLANG_USE_MLX requires stable Torch 2.13.x and MLX >= 0.32.0; \"\n            \"found \"\n            f\"Torch {torch_version or 'unknown'} + MLX {mlx_version or 'unknown'}; \"\n            \"reinstall with the srt_mps extra\"\n        )\n\n    mps_backend = getattr(torch.backends, \"mps\", None)\n    is_mps_available = getattr(mps_backend, \"is_available\", None)","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/hardware_backend/mlx/runtime.py#L17-L53","documentation":"Raised by SGLang's MLX runtime validator when SGLANG_USE_MLX is enabled but the `mlx` Python package cannot be imported. The MLX hardware backend (Apple Silicon MPS path) requires both a stable Torch 2.13.x and MLX >= 0.32.0, so a missing MLX install fails fast with an actionable message pointing to the `srt_mps` extra.","triggerScenarios":"Setting SGLANG_USE_MLX=1 (which calls use_mlx() -> _validate_runtime()) on a machine where `import mlx.core` raises ImportError — e.g. MLX was never installed, installed in a different venv, or installed via an incompatible wheel/platform (Linux x86 instead of macOS Apple Silicon).","commonSituations":"Enabling the MLX backend without installing the srt_mps extra; wrong conda/venv activated; trying MLX on non-Apple-Silicon hardware; CI runners without the MLX dependency.","solutions":["Install the MLX extra: pip install -e \".[srt_mps]\" (or pip install mlx>=0.32.0) in the same environment SGLang runs in","Verify with `python -c \"import mlx.core as mx; print(mx.__version__)\"` that MLX is importable and >= 0.32.0","Confirm you are on macOS Apple Silicon; MLX is unavailable elsewhere","Unset SGLANG_USE_MLX if you did not intend to use the MPS backend"],"exampleFix":"# before\nexport SGLANG_USE_MLX=1\npython -m sglang.launch_server ...\n# after\npip install -e \".[srt_mps]\"\npython -c \"import mlx.core as mx; print(mx.__version__)\"  # >= 0.32.0\nexport SGLANG_USE_MLX=1\npython -m sglang.launch_server ...","handlingStrategy":"validation","validationCode":"import importlib.util, os\nif os.environ.get(\"SGLANG_USE_MLX\"):\n    if importlib.util.find_spec(\"mlx\") is None:\n        raise SystemExit(\"Install the srt_mps extra before enabling SGLANG_USE_MLX\")","typeGuard":null,"tryCatchPattern":"try:\n    from sglang.srt.hardware_backend.mlx.runtime import use_mlx\n    use_mlx()\nexcept RuntimeError as e:\n    if \"srt_mps extra\" in str(e):\n        logger.warning(\"MLX backend unavailable: %s\", e)\n        # fall back to default backend\n    else:\n        raise","preventionTips":["Install SGLang with the srt_mps extra on Apple Silicon","Smoke-test `import mlx.core` in the launch script before starting the server","Keep one venv per backend to avoid mlx/torch env drift"],"tags":["mlx","apple-silicon","dependency-missing","mps","sglang"],"backgroundTag":"missing-dependency","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}