Installing Ray

Install Ray on Linux, macOS, or Windows using pip, conda, Docker, or build from source.

Ray currently officially supports x86_64, aarch64 (ARM) for Linux, and Apple silicon (M1) hardware. Ray on Windows is currently in beta.

Install with pip

The simplest way to install Ray is from PyPI.

Minimal install

pip install -U "ray"

The default install does not include the dashboard, cluster launcher, or runtime environment dependencies. For most use cases, install ray[default] or pick the extras you need.

Available extras

Extra	Includes
default	Core Ray, dashboard, cluster launcher, log aggregation
data	Ray Data
train	Ray Train
tune	Ray Tune
serve	Ray Serve
serve-grpc	Ray Serve with gRPC support
rllib	RLlib for reinforcement learning
client	Ray Client (deprecated, prefer Ray Jobs)
observability	Ray observability tooling
all	All of the above

Install nightly builds

Nightly releases are tested via automation but do not undergo full release-process review. Use them for previewing upcoming features.

pip install -U "ray[default] @ https://s3-us-west-2.amazonaws.com/ray-wheels/latest/ray-3.0.0.dev0-cp311-cp311-manylinux2014_x86_64.whl"

Replace the wheel URL with the one matching your Python version, OS, and architecture. The full list lives in the Ray release notes.

Install from a specific commit

To pin to a specific Ray commit, replace <COMMIT_HASH> and the wheel filename with the values for your platform:

pip install -U "ray[default] @ https://s3-us-west-2.amazonaws.com/ray-wheels/master/<COMMIT_HASH>/ray-3.0.0.dev0-cp311-cp311-manylinux2014_x86_64.whl"

Run Ray with Docker

The official Ray image is published on Docker Hub.

docker pull rayproject/ray
docker run --shm-size=4gb -t -i rayproject/ray

Available image variants:

• rayproject/ray — base Ray image with CPU support
• rayproject/ray-ml — Ray plus common ML libraries (PyTorch, TensorFlow, scikit-learn)
• rayproject/ray:<version>-gpu — CUDA-enabled images

Install on macOS Apple silicon

Ray supports Apple silicon natively. Install with pip as usual:

pip install -U "ray[default]"

If you encounter build errors with optional dependencies, ensure you have a recent Xcode Command Line Tools installation: xcode-select --install.

Install on Windows

Ray on Windows is currently in beta. Functionality, performance, and stability may differ from Linux and macOS.

Install Visual C++ Build Tools, then:

pip install -U "ray[default]"

Build from source

To contribute to Ray or install a development version, build from source.

1. Clone the repository

   git clone https://github.com/ray-project/ray.git
   cd ray
   
2. Install build dependencies

   Follow the instructions in BUILD.rst for your platform. You’ll need Bazel, a C++ compiler, and Python development headers.

3. Build the Python wheel

   cd python
   pip install -e . --verbose
   

Verify the installation

import ray
ray.init()
print(ray.cluster_resources())

You should see a dictionary of available cluster resources (CPUs, memory, and any detected GPUs).

Next steps

Quickstart

Run your first Ray program.

Ray Core walkthrough

Learn the core Ray API.