Installing Ray

Tip

Join our community slack to discuss Ray!

Ray currently supports MacOS and Linux. Windows wheels are now available, but Windows support is experimental and under development.

Latest stable version

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

pip install -U ray  # also recommended: ray[debug]

Note for Windows Users: To use Ray on Windows, Visual C++ runtime must be installed (see Windows Dependencies section). If you run into any issues, please see the Windows Support section.

Latest Snapshots (Nightlies)

Here are links to the latest wheels (which are built for each commit on the master branch). To install these wheels, use the following pip command and wheels instead of the ones above:

pip install -U [link to wheel]

Linux

MacOS

Windows (experimental)

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

Windows Python 3.6

Linux Python 3.5

MacOS Python 3.5

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://ray-wheels.s3-us-west-2.amazonaws.com/master/{COMMIT_HASH}/ray-{RAY_VERSION}-{PYTHON_VERSION}-{PYTHON_VERSION}m-{OS_VERSION}_intel.whl

For example, here are the Ray 0.9.0.dev0 wheels for Python 3.5, MacOS for commit a0ba4499ac645c9d3e82e68f3a281e48ad57f873:

pip install https://ray-wheels.s3-us-west-2.amazonaws.com/master/a0ba4499ac645c9d3e82e68f3a281e48ad57f873/ray-0.9.0.dev0-cp35-cp35m-macosx_10_13_intel.whl

Installing Dashboard

The dashboard requires a few additional Python packages, which can be installed via pip.

pip install ray[dashboard]

The command ray.init() or ray start --head will print out the address of the dashboard. For example,

>>> import ray
>>> ray.init()
======================================================================
View the dashboard at http://127.0.0.1:8265.
Note: If Ray is running on a remote node, you will need to set up an
SSH tunnel with local port forwarding in order to access the dashboard
in your browser, e.g. by running 'ssh -L 8265:127.0.0.1:8265
<username>@<host>'. Alternatively, you can set dashboard_host="0.0.0.0" in
the call to ray.init() to allow direct access from external machines.
======================================================================

Windows Support

Windows support is currently limited and “alpha” quality. Bugs, process/resource leaks, or other incompatibilities may exist under various scenarios. Unusual, unattended, or production usage is not recommended.

To use Ray on Windows, the Visual C++ runtime must be installed (see Windows Dependencies section).

If you encounter any issues, please try the following:

If your issue has not yet been addressed, comment on the Windows Known Issues page.

Windows Dependencies

For Windows, ensure the latest Visual C++ runtime (install link) is installed before using Ray.

Otherwise, you may receive an error similar to the following when Ray fails to find the runtime library files (e.g. VCRUNTIME140_1.dll):

FileNotFoundError: Could not find module '_raylet.pyd' (or one of its dependencies).

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 and want to use Ray in a defined environment, e.g, ray, use these commands:

conda create --name ray
conda activate ray
conda install --name ray pip
pip install ray

Use pip list to confirm that ray is installed.

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

Run the script to create Docker images.

cd ray
./build-docker.sh

This script creates several Docker images:

  • The ray-project/deploy image is a self-contained copy of code and binaries suitable for end users.

  • The ray-project/examples adds additional libraries for running examples.

  • The ray-project/base-deps image builds from Ubuntu Xenial and includes Anaconda and other basic dependencies and can serve as a starting point for developers.

Review images by listing them:

docker images

Output should look something like the following:

REPOSITORY                          TAG                 IMAGE ID            CREATED             SIZE
ray-project/examples                latest              7584bde65894        4 days ago          3.257 GB
ray-project/deploy                  latest              970966166c71        4 days ago          2.899 GB
ray-project/base-deps               latest              f45d66963151        4 days ago          2.649 GB
ubuntu                              xenial              f49eec89601e        3 weeks ago         129.5 MB

Launch Ray in Docker

Start out by launching the deployment container.

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

Replace <shm-size> with a limit appropriate for your system, for example 512M or 2G. The -t and -i options here are required to support interactive use of the container.

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