Contribution Guide

​

Install SGLang from Source

​

Prepare Environment

​

Fork and clone the repository

git clone https://github.com/<your_user_name>/sglang.git
# if you are using docker, the environment is already set up.
cd sglang
export PYTHONPATH=$PWD/python:$PYTHONPATH

​

Format code with pre-commit

pip3 install pre-commit
pre-commit install
pre-commit run --all-files

• pre-commit run --all-files manually runs all configured checks, applying fixes if possible. If it fails the first time, re-run it to ensure lint errors are fully resolved. Make sure your code passes all checks before creating a Pull Request.
• Do not commit directly to the main branch. Always create a new branch (e.g., feature/my-new-feature), push your changes, and open a PR from that branch.
• Link checking with lychee is enforced in CI. By default, it is not blocking local commits.
• To run local link checks manually, use: pre-commit run --hook-stage manual lychee --all-files.

​

Run and add tests

ascend/
├── llm_models/          # Per-model inference accuracy
├── vlm_models/          # Vision-language models
├── embedding_models/    # Embedding model tests
├── rerank_models/       # Reranker model tests
├── reward_models/       # Reward model tests
├── interface/           # API correctness, function calling
├── basic_function/      # Cache, sampling, quantization, etc.
└── test_npu_memory_consumption.py

​

Adding a test

1. Place your test file in the appropriate directory under test/registered/ascend/.
2. Extend CustomTestCase (from sglang.test.test_utils) for CI retry support.
3. Launch server with popen_launch_server() in setUpClass and clean up with kill_process_tree() in tearDownClass.
4. Register your test with register_npu_ci():
   from sglang.test.ci.ci_register import register_npu_ci
   register_npu_ci(est_time=400, suite="stage-b-test-1-npu-a2", nightly=False)
   register_npu_ci(est_time=400, suite="nightly-1-npu-a3", nightly=True)
   

​

Running tests locally

pytest test/registered/ascend/llm_models/test_npu_qwen3_0_6b.py -v

​

Register models for CI

1. Register account and upload your model to modelscope.
2. Make sure your model is pre-cached on the CI server and is at the path “/data/ascend-ci-share-pkking-sglang/modelscope/hub/models//”. If this is not the case, use following command on CI server:
   modelscope download \
     --model {your_model_repo}/{your_model} \
     --local_dir /data/ascend-ci-share-pkking-sglang/modelscope/hub/models/{your_model_repo}/{your_model}
   

Note: If you don’t have access to CI server, please ask maintainers (zl19940307@163.com) to download your model.

3. Add model to python/sglang/test/ascend/test_ascend_utils.py (use docker "/root/.cache/modelscope/hub/models/{your_model_repo}/{your_model}" path).

​

Write documentation

​

Test the accuracy

# Launch a server
python3 -m sglang.launch_server --model Qwen/Qwen2-7B-Instruct

# Evaluate. --base-url must point at the server launched above.
# The default SGLang server port is 30000; change it if you launched
# the server with a different --port.
python3 -m sglang.test.run_eval --base-url http://localhost:30000 --eval-name gsm8k --num-examples 200

• test_eval_accuracy_large.py
• test_gpt_oss_1gpu.py

​

Benchmark the speed

​

Requesting a review for merge

​

How to Trigger CI Tests

• /tag-run-ci-label: Adds the “run-ci” label. Only future commits trigger CI; the current commit is unaffected. Add the extra argument (/tag-run-ci-label extra) to additionally apply the “run-ci-extra” label, opting the PR into the extra test workflow (pr-test-extra.yml).
• /rerun-failed-ci: Reruns workflows from the latest commit with conclusion failed, flaky, or skipped.
• /tag-and-rerun-ci: Runs both. Use this on a fresh PR to kick off CI on the current commit — /tag-run-ci-label alone won’t. Accepts the same extra argument (/tag-and-rerun-ci extra).
• /rerun-stage <stage-name>: Reruns a single test stage without waiting for its dependencies. Useful for quickly validating a specific test fix instead of waiting ~30 minutes for preceding stages.
• /rerun-test <test-spec> [<test-spec> ...]: Reruns one or more specific tests directly, bypassing stage boundaries. Each <test-spec> is pytest-style <file>::<TestClass>[.<test_method>] (the ::TestClass and .<test_method> parts are optional). The handler resolves each spec, groups specs by their registered runner-label, and dispatches one Rerun Test workflow per group. Examples: /rerun-test test_srt_endpoint.py, /rerun-test registered/core/test_srt_endpoint.py::TestSRTEndpoint.test_simple_decode, /rerun-test test_a.py test_b.py (multiple at once).

​

CI rate limits

cool-down-minutes:
  description: "Cooldown period in minutes for low-permission users; 0 disables rate limiting"
  type: number
  default: 120

​

Code style guidance

• Avoid code duplication. If the same code snippet (more than five lines) appears multiple times, extract it into a shared function.
• Minimize device synchronization. Reduce expensive CPU-NPU synchronization operations, such as tensor.item() or tensor.cpu(), whenever possible. Use vectorized code.
• Prioritize extreme efficiency. SGLang is a runtime, and most of your code runs on the critical path for every request. Optimize all minor overheads as much as possible, especially in the model forward code.
  • A common pattern is some runtime checks in the model forward pass (e.g., this). These are very likely the same for every layer. Please cache the result as a single boolean value in __init__ whenever possible.
• Make functions as pure as possible. Avoid in-place modification of arguments.
• Keep files concise. If a file exceeds 2,000 lines of code, split it into multiple smaller files. (e.g., scheduler.py, scheduler_pp_mixin.py)
• In a file, put core data structures at the top of the file. Put utility functions at the bottom of the file.
• Keep tests run fast.
  • If a single test file run longer than 500 seconds, split it into multiple smaller files (e.g., test_eagle_infer_a.py, test_eagle_infer_b.py).
  • If a single job in a github workflow runs longer than 30 min, split it into smaller jobs/steps.
  • Reuse server launches in your unit tests to make tests run faster.
• Never use pickle.loads(), pickle.load(), or recv_pyobj() to deserialize untrusted or network-received data. Python’s pickle module is not secure — it can execute arbitrary code during deserialization. Use safe serialization formats such as msgpack or JSON instead.
• When supporting new hardware or features, follow these guidelines:
  • Do not drastically change existing code.
  • Always prefer new files to introduce specific components for your new hardware (e.g., allocator_npu.py).
  • If you write multiple if/else blocks for new features, ensure the common path (e.g., NVIDIA hardware or the existing code path) is the first branch.

​

How to update sgl-kernel-npu

​

Multi-PR workflow

1. Submit sgl-kernel-npu PR: Add or modify operators in the sgl-kernel-npu repository following the operator development guide. Ensure all tests pass.
2. Bump sgl-kernel-npu version: Update the version number. Merging triggers an automatic PyPI release. If not urgent, wait for a regular release (typically within one week).
3. Reference the new version in SGLang:
   • Update the SGLANG_KERNEL_NPU_TAG argument in docker/npu.Dockerfile to the new sgl-kernel-npu release tag.
   • Use the new operator in SGLang code.

​

Tips for newcomers

• Mini-SGLang for a quick overview on the structure of sglang.
• Code Walk-through for a deeper look into SGLang’s workflow.
• GTC-2026 Training Lab for hands-on practices of how to do optimization, benchmarking, or profiling on a launched SGLang instance.