| name | rebuild |
| description | Rebuild Ray from source — determines the right build mode based on what changed |
Rebuild Ray
Canonical build docs: doc/source/ray-contribute/development.md
Use the user's configured Python from CLAUDE.local.md, or fall back to which python.
Update this skill if any changes are detected in development.rst.
Determine what to rebuild
- Check what files changed:
git diff --name-only HEAD (or ask the user)
- Pick the appropriate build mode:
- Only .py files changed (no .h, .cc, .pyx, .pxd) → Python-only rebuild (not required if installed with
pip install -e . — editable mode auto-picks up Python changes)
- .h, .cc, .pyx, .pxd files changed → C++/Cython rebuild
- Dashboard files changed (python/ray/dashboard/client/) → Dashboard rebuild first
- First time / clean build → Full source build
Running Python tests that exercise C++ changes: When a Python test depends on
C++ or Cython code (raylet, GCS, core_worker, etc.), run the C++/Cython rebuild
below before running the test. Editable Python installs do not rebuild the compiled
extensions, so stale binaries will run otherwise.
Python-only rebuild
For changes to Tune, RLlib, Autoscaler, and most Python files.
Two approaches depending on how Ray was installed:
If installed with pip install -e . (editable/full source build)
No rebuild needed — Python changes are picked up automatically.
If installed from nightly wheel + setup-dev.py
- Ensure a nightly wheel is installed (see doc/source/ray-contribute/development.md
for the correct wheel URL for the user's platform and Python version)
- Link local files:
python python/ray/setup-dev.py
- Can skip specific dirs:
python python/ray/setup-dev.py -y --skip _private dashboard
Warning: With setup-dev.py, don't run pip uninstall ray or pip install -U.
Instead: rm -rf <site-packages>/ray, reinstall wheel, re-run setup-dev.py.
C++/Cython rebuild (after initial full build)
Full package rebuild
bazel run //:gen_ray_pkg
Build individual modules (faster)
bazel build //src/ray/raylet:raylet
bazel build //src/ray/gcs:gcs_server
bazel build //src/ray/core_worker:core_worker
bazel build //:ray_pkg
Build variants
bazel run -c fastbuild //:gen_ray_pkg — fast build (less optimization)
bazel run -c dbg //:gen_ray_pkg — debug build with symbols (for gdb)
bazel run -c opt //:gen_ray_pkg — optimized build
Make permanent in ~/.bazelrc: build --compilation_mode=fastbuild
Full source build (first time)
- If dashboard changed:
cd python/ray/dashboard/client && npm ci && npm run build && cd -
- Install deps:
cd python/ && pip install -r requirements.txt
- Build:
pip install -e . --verbose
Resource-constrained builds
Add to ~/.bazelrc if machine runs out of memory:
build --local_ram_resources=HOST_RAM*.5 --local_cpu_resources=4
build --disk_cache=~/bazel-cache
Worktree notes
- Verify build paths:
bazel info execution_root
- If build fails, check .bazelversion matches installed Bazel
- Each worktree may need its own
pip install -e .
- If in a worktree and bazel targets fail, ensure symlinks are correct