Installing Ray

Ray currently supports Linux, MacOS and Windows. Ray on Windows is currently in beta.

Official Releases

You can install the latest official version of Ray as follows.

# Install Ray with support for the dashboard + cluster launcher
pip install -U "ray[default]"

# Install Ray with minimal dependencies
# pip install -U ray

To install Ray libraries:

pip install -U "ray[air]" # installs Ray + dependencies for Ray AI Runtime
pip install -U "ray[tune]"  # installs Ray + dependencies for Ray Tune
pip install -U "ray[rllib]"  # installs Ray + dependencies for Ray RLlib
pip install -U "ray[serve]"  # installs Ray + dependencies for Ray Serve

Daily Releases (Nightlies)

You can install the nightly Ray wheels via the following links. These daily releases are tested via automated tests but do not go through the full release process. To install these wheels, use the following pip command and wheels:

# Clean removal of previous install
pip uninstall -y ray
# Install Ray with support for the dashboard + cluster launcher
pip install -U "ray[default] @ LINK_TO_WHEEL.whl"

# Install Ray with minimal dependencies
# pip install -U LINK_TO_WHEEL.whl

Linux

MacOS

Windows (beta)

Linux Python 3.10

MacOS Python 3.10

Windows Python 3.10

Linux Python 3.9

MacOS Python 3.9

Windows Python 3.9

Linux Python 3.8

MacOS Python 3.8

Windows Python 3.8

Linux Python 3.7

MacOS Python 3.7

Windows Python 3.7

Linux Python 3.6

MacOS Python 3.6

Note

Python 3.10 support is currently experimental.

Note

On Windows, support for multi-node Ray clusters is currently experimental and untested. If you run into issues please file a report at https://github.com/ray-project/ray/issues.

Note

Usage stats collection is enabled by default (can be disabled) for nightly wheels including both local clusters started via ray.init() and remote clusters via cli.

Installing from a specific commit

You can install the Ray wheels of any particular commit on master with the following template. You need to specify the commit hash, Ray version, Operating System, and Python version:

pip install https://s3-us-west-2.amazonaws.com/ray-wheels/master/{COMMIT_HASH}/ray-{RAY_VERSION}-{PYTHON_VERSION}-{PYTHON_VERSION}m-{OS_VERSION}.whl

For example, here are the Ray 3.0.0.dev0 wheels for Python 3.7, MacOS for commit ba6cebe30fab6925e5b2d9e859ad064d53015246:

pip install https://s3-us-west-2.amazonaws.com/ray-wheels/master/ba6cebe30fab6925e5b2d9e859ad064d53015246/ray-3.0.0.dev0-cp37-cp37m-macosx_10_15_intel.whl

There are minor variations to the format of the wheel filename; it’s best to match against the format in the URLs listed in the Nightlies section. Here’s a summary of the variations:

  • For Python 3.8 and 3.9, the m before the OS version should be deleted and the OS version for MacOS should read macosx_10_15_x86_64 instead of macosx_10_15_intel.

  • For MacOS, commits predating August 7, 2021 will have macosx_10_13 in the filename instad of macosx_10_15.

Install Ray Java with Maven

Before installing Ray Java with Maven, you should install Ray Python with pip install -U ray . Note that the versions of Ray Java and Ray Python must match. Note that nightly Ray python wheels are also required if you want to install Ray Java snapshot version.

The latest Ray Java release can be found in central repository. To use the latest Ray Java release in your application, add the following entries in your pom.xml:

<dependency>
  <groupId>io.ray</groupId>
  <artifactId>ray-api</artifactId>
  <version>${ray.version}</version>
</dependency>
<dependency>
  <groupId>io.ray</groupId>
  <artifactId>ray-runtime</artifactId>
  <version>${ray.version}</version>
</dependency>

The latest Ray Java snapshot can be found in sonatype repository. To use the latest Ray Java snapshot in your application, add the following entries in your pom.xml:

<!-- only needed for snapshot version of ray -->
<repositories>
  <repository>
    <id>sonatype</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    <releases>
      <enabled>false</enabled>
    </releases>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>io.ray</groupId>
    <artifactId>ray-api</artifactId>
    <version>${ray.version}</version>
  </dependency>
  <dependency>
    <groupId>io.ray</groupId>
    <artifactId>ray-runtime</artifactId>
    <version>${ray.version}</version>
  </dependency>
</dependencies>

Note

When you run pip install to install Ray, Java jars are installed as well. The above dependencies are only used to build your Java code and to run your code in local mode.

If you want to run your Java code in a multi-node Ray cluster, it’s better to exclude Ray jars when packaging your code to avoid jar conficts if the versions (installed Ray with pip install and maven dependencies) don’t match.

M1 Mac (Apple Silicon) Support

Ray has experimental support for machines running Apple Silicon (such as M1 macs). To get started:

  1. Install miniforge.

    • wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh

    • bash Miniforge3-MacOSX-arm64.sh

    • rm https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh # Cleanup.

  2. Ensure you’re using the miniforge environment (you should see (base) in your terminal).

    • source ~/.bash_profile

    • conda activate

  3. Ensure that the grpcio package is installed via forge and not pypi. Grpcio currently requires special compilation flags, which pypi will _not_ correctly build with. Miniforge provides a prebuilt version of grpcio for M1 macs.

    • pip uninstall grpcio; conda install grpcio=1.43.0

  4. Install Ray as you normally would.

    • pip install ray

Note

At this time, Apple Silicon ray wheels are being published for releases only. As support stabilizes, nightly wheels will be published in the future.

Windows Support

Windows support is currently in beta. Please submit any issues you encounter on GitHub.

Installing Ray on Arch Linux

Note: Installing Ray on Arch Linux is not tested by the Project Ray developers.

Ray is available on Arch Linux via the Arch User Repository (AUR) as python-ray.

You can manually install the package by following the instructions on the Arch Wiki or use an AUR helper like yay (recommended for ease of install) as follows:

yay -S python-ray

To discuss any issues related to this package refer to the comments section on the AUR page of python-ray here.

Installing Ray with Anaconda

If you use Anaconda (installation instructions) and want to use Ray in a defined environment, e.g, ray, use these commands:

conda config --env --add channels conda-forge
conda env create -n ray  # works with mamba too
conda activate ray
pip install ray  # or `conda install ray-core`

For a complete list of available ray libraries on Conda-forge, have a look at: https://github.com/conda-forge/ray-packages-feedstock

Note

Ray conda packages are maintained by the community, not the Ray team. While using a conda environment, it is recommended to install Ray from PyPi using pip install ray in the newly created environment.

Building Ray from Source

Installing from pip should be sufficient for most Ray users.

However, should you need to build from source, follow these instructions for building Ray.

Docker Source Images

Most users should pull a Docker image from the Ray Docker Hub.

  • The rayproject/ray images include Ray and all required dependencies. It comes with anaconda and various versions of Python.

  • The rayproject/ray-ml images include the above as well as many additional ML libraries.

  • The rayproject/base-deps and rayproject/ray-deps images are for the Linux and Python dependencies respectively.

Images are tagged with the format {Ray version}[-{Python version}][-{Platform}]. Ray version tag can be one of the following:

Ray version tag

Description

latest

The most recent Ray release.

x.y.z

A specific Ray release, e.g. 1.12.1

nightly

The most recent Ray development build (a recent commit from Github master)

6 character Git SHA prefix

A specific development build (uses a SHA from the Github master, e.g. 8960af).

The optional Python version tag specifies the Python version in the image. All Python versions supported by Ray are available, e.g. py37, py38, py39 and py310. If unspecified, the tag points to an image using Python 3.7.

The optional Platform tag specifies the platform where the image is intended for:

Platform tag

Description

-cpu

These are based off of an Ubuntu image.

-cuXX

These are based off of an NVIDIA CUDA image with the specified CUDA version. They require the Nvidia Docker Runtime.

-gpu

Aliases to a specific -cuXX tagged image.

<no tag>

Aliases to -cpu tagged images. For ray-ml image, aliases to -gpu tagged image.

Example: for the nightly image based on Python 3.8 and without GPU support, the tag is nightly-py38-cpu.

If you want to tweak some aspect of these images and build them locally, refer to the following script:

cd ray
./build-docker.sh

Beyond creating the above Docker images, this script can also produce the following two images.

  • The rayproject/development image has the ray source code included and is setup for development.

  • The rayproject/examples image adds additional libraries for running examples.

Review images by listing them:

docker images

Output should look something like the following:

REPOSITORY                          TAG                 IMAGE ID            CREATED             SIZE
rayproject/ray                      latest              7243a11ac068        2 days ago          1.11 GB
rayproject/ray-deps                 latest              b6b39d979d73        8 days ago          996  MB
rayproject/base-deps                latest              5606591eeab9        8 days ago          512  MB
ubuntu                              focal               1e4467b07108        3 weeks ago         73.9 MB

Launch Ray in Docker

Start out by launching the deployment container.

docker run --shm-size=<shm-size> -t -i rayproject/ray

Replace <shm-size> with a limit appropriate for your system, for example 512M or 2G. A good estimate for this is to use roughly 30% of your available memory (this is what Ray uses internally for its Object Store). The -t and -i options here are required to support interactive use of the container.

If you use a GPU version Docker image, remember to add --gpus all option. Replace <ray-version> with your target ray version in the following command:

docker run --shm-size=<shm-size> -t -i --gpus all rayproject/ray:<ray-version>-gpu

Note: Ray requires a large amount of shared memory because each object store keeps all of its objects in shared memory, so the amount of shared memory will limit the size of the object store.

You should now see a prompt that looks something like:

root@ebc78f68d100:/ray#

Test if the installation succeeded

To test if the installation was successful, try running some tests. This assumes that you’ve cloned the git repository.

python -m pytest -v python/ray/tests/test_mini.py