sgl-project/sglang · critical · ImportError

Ray is required for --use-ray mode. Install it with: pip ins

Error message

Ray is required for --use-ray mode. Install it with: pip install 'sglang[ray]'

What it means

launch_server's run_server raises ImportError when --use-ray is set and sglang.srt.ray.http_server cannot be imported, which in practice means the ray extra is not installed. The error message tells you to install the optional ray dependency.

Source

Thrown at python/sglang/launch_server.py:49

            asyncio.run(serve_grpc_encoder(server_args))
        else:
            from sglang.srt.disaggregation.encoder.http_server import launch_server

            launch_server(server_args)
    elif cfg.smg_grpc_mode:
        # Legacy SMG gRPC server (--smg-grpc-mode, or the deprecated --grpc-mode
        # which __post_init__ folds into smg_grpc_mode). The native Rust gRPC
        # server is a separate path, enabled by --grpc-port, that starts
        # alongside the default HTTP server below.
        from sglang.srt.entrypoints.grpc_server import serve_grpc

        asyncio.run(serve_grpc(server_args))
    elif cfg.use_ray:
        # Ray mode: HTTP mode with Ray backend.
        try:
            from sglang.srt.ray.http_server import launch_server
        except ImportError:
            raise ImportError(
                "Ray is required for --use-ray mode. "
                "Install it with: pip install 'sglang[ray]'"
            )

        launch_server(server_args)
    else:
        # Default mode: HTTP mode.
        from sglang.srt.entrypoints.http_server import launch_server

        launch_server(server_args)


if __name__ == "__main__":
    warnings.warn(
        "'python -m sglang.launch_server' is still supported, but "
        "'sglang serve' is the recommended entrypoint.\n"
        "  Example: sglang serve --model-path <model> [options]",
        UserWarning,

View on GitHub (pinned to 0132848349)

Solutions

1. Install the extra: pip install 'sglang[ray]'
2. Verify with python -c 'import ray' and re-run the launch command
3. If ray is installed but import still fails, check for version conflicts or a broken sglang install (pip install --force-reinstall sglang)

Example fix

# before
pip install sglang
python -m sglang.launch_server --model ... --use-ray

# after
pip install 'sglang[ray]'
python -m sglang.launch_server --model ... --use-ray

try:
    import ray  # noqa
    HAS_RAY = True
except ImportError:
    HAS_RAY = False
if args.use_ray and not HAS_RAY:
    raise SystemExit("Install first: pip install 'sglang[ray]'")

When it happens

Trigger: Running python -m sglang.launch_server ... --use-ray without the ray package installed (sglang[ray] extra), so the import of the Ray HTTP server module fails.

Common situations: Fresh environments with a bare pip install sglang (no extras), Docker images built without ray, or ray uninstalled/downgraded as a side effect of another package.

Related errors

• Please install mooncake by following the instructions at htt
• gRPC mode requires the smg-grpc-servicer package. If not ins
• --enable-metrics requires smg-grpc-servicer ≥ 0.5.3 (the ver
• ModelOpt is not available. Please install modelopt.
• {flashinfer_error}

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