Environment:Ray project Ray Python Runtime Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Distributed_Computing |
| Last Updated | 2026-02-13 16:35 GMT |
Overview
Python 3.10+ runtime environment with core dependencies for running the Ray distributed computing framework.
Description
This environment defines the Python runtime requirements for running Ray. It requires Python 3.10 or higher (with support for 3.10, 3.11, 3.12, 3.13, and 3.14). The core package has minimal dependencies including Click, msgpack, protobuf, and PyYAML. Optional extras extend functionality for ML (NumPy, pandas, PyArrow), serving (gRPC, aiohttp), GPU acceleration (cupy-cuda12x on Linux only), and reinforcement learning (Gymnasium). The build process requires Cython >= 3.0.12 and Bazel 6.5.0 exactly.
Usage
Use this environment for any Ray workload: task execution, actor management, Serve deployments, Tune hyperparameter optimization, or RLlib reinforcement learning. This is the base prerequisite for all Python-based Ray functionality. Platform-specific constraints apply: GPU support (cupy-cuda12x) is unavailable on macOS, and memray profiling is unavailable on Windows.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux (Ubuntu 20.04+), macOS, or Windows | Windows excludes MinGW/MSYS/Cygwin; some features limited |
| Python | >= 3.10 | Supported: 3.10, 3.11, 3.12, 3.13, 3.14 |
| Build Tool | Bazel 6.5.0 (exact) | Required only for building from source |
| Build Tool | Cython >= 3.0.12 | Required only for building from source |
| Architecture | x86_64 or aarch64 (ARM64) | Both tested in CI |
Dependencies
Core Python Packages
- `click` >= 7.0
- `filelock`
- `jsonschema`
- `msgpack` >= 1.0.0, < 2.0.0
- `packaging` >= 24.2
- `protobuf` >= 3.20.3
- `pyyaml`
- `requests`
Optional Extras (ML)
- `numpy` >= 1.20
- `pandas` >= 1.3
- `pyarrow` >= 9.0.0
Optional Extras (Serve)
- `grpcio` >= 1.42.0 (except != 1.56.0 on macOS)
- `aiohttp` >= 3.13.3
- `opentelemetry-sdk` >= 1.30.0
- `prometheus_client` >= 0.7.1
- `ormsgpack` >= 1.7.0
Optional Extras (GPU)
- `cupy-cuda12x` (Linux only, not macOS)
Optional Extras (LLM)
- `vllm` >= 0.15.0
- `transformers` >= 4.57.3
Build Requirements
- `cython` >= 3.0.12
- `pip`
- `wheel`
Credentials
The following environment variables control the build process:
- `RAY_BUILD_CORE`: Enable/disable core build (default: "1")
- `RAY_INSTALL_JAVA`: Enable Java build (default: "0")
- `RAY_DISABLE_EXTRA_CPP`: Disable C++ extras (set to "1")
- `RAY_BUILD_REDIS`: Enable Redis build (default: "1")
- `SKIP_BAZEL_BUILD`: Skip Bazel compilation (set to "1")
- `BAZEL_ARGS`: Additional Bazel build arguments
- `BAZEL_LIMIT_CPUS`: Limit Bazel CPU usage
- `RAY_DEBUG_BUILD`: Build type ("debug", "asan", "tsan", "deps-only")
Quick Install
# Install Ray with core dependencies
pip install ray
# Install Ray with ML extras
pip install "ray[data]"
# Install Ray with Serve extras
pip install "ray[serve]"
# Install Ray with all extras
pip install "ray[all]"
Code Evidence
Python version constraint from `python/setup.py:25`:
SUPPORTED_PYTHONS = [(3, 10), (3, 11), (3, 12), (3, 13), (3, 14)]
Python requires declaration from `python/setup.py:819`:
python_requires=">=3.10",
Core dependencies from `python/setup.py:395-404`:
setup_spec.install_requires = [
"click>=7.0",
"filelock",
"jsonschema",
"msgpack >= 1.0.0, < 2.0.0",
"packaging>=24.2",
"protobuf>=3.20.3",
"pyyaml",
"requests",
]
Build tool requirements from `python/setup.py:833`:
setup_requires=["cython >= 3.0.12", "pip", "wheel"],
Build configuration environment variables from `python/setup.py:30-36`:
BUILD_CORE = os.getenv("RAY_BUILD_CORE", "1") == "1"
BUILD_JAVA = os.getenv("RAY_INSTALL_JAVA", "0") == "1"
BUILD_CPP = os.getenv("RAY_DISABLE_EXTRA_CPP") != "1"
BUILD_REDIS = os.getenv("RAY_BUILD_REDIS", "1") == "1"
SKIP_BAZEL_BUILD = os.getenv("SKIP_BAZEL_BUILD") == "1"
BAZEL_ARGS = os.getenv("BAZEL_ARGS")
BAZEL_LIMIT_CPUS = os.getenv("BAZEL_LIMIT_CPUS")
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Python version not supported` | Python < 3.10 installed | Upgrade to Python 3.10 or higher |
| `ModuleNotFoundError: No module named 'cython'` | Missing build dependency | `pip install "cython>=3.0.12"` before building from source |
| `cupy not available on darwin` | Attempting GPU on macOS | GPU acceleration via cupy-cuda12x is Linux-only |
| Platform rejected (MinGW/MSYS/Cygwin) | Invalid Windows Python build | Use official CPython for Windows, not MinGW builds |
Compatibility Notes
- macOS: GPU support (cupy-cuda12x) is explicitly excluded. gRPC version 1.56.0 is excluded due to compatibility issues.
- Windows: memray profiling is excluded. MinGW, MSYS, and Cygwin Python builds are explicitly rejected.
- Python 3.12+: Requires py-spy >= 0.4.0 (older versions need >= 0.2.0).
- Python < 3.11: Requires the `async-timeout` backport package.
- aarch64: Dependency resolution has known limitations in CI ("Resolution currently does not work on aarch64").