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.
Official Releases¶
You can install the latest official version of Ray as follows. Official releases are produced according to the release process doc.
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.
Daily Releases (Nightlies)¶
You can install the latest Ray wheels via the following command. These daily releases are tested via automated tests but do not go through the full release process:
pip install -U ray
ray install-nightly
Note
ray install-nightly may not capture updated library dependencies. After running ray install-nightly, consider running pip install ray[<library>] without upgrading (via -U) to update dependencies.
Note
If you’re currently on ray<=1.0.1.post1, ray install-nightly will not install the most recent nightly wheels. Please use the links below instead.
Alternatively, here are the 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) |
|---|---|---|
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 1.1.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-1.1.0.dev0-cp35-cp35m-macosx_10_13_intel.whl
Install Ray With Maven¶
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 or single machine 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.
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:
Check the Windows Known Issues page on GitHub to see the latest updates on Windows support.
In the case that your issue has been addressed, try installing the latest nightly wheels.
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¶
Most users should pull a Docker image from the Ray Docker Hub.
The
rayproject/rayimage has ray and all required dependencies. It comes with anaconda and Python 3.7.The
rayproject/autoscalerimage has the above features as well as many additional libraries.The
rayproject/base-depsandrayproject/ray-depsare for the linux and python dependencies respectively.
These images are tagged by their release number (or commit hash for nightlies) as well as a "-gpu" if they are GPU compatible.
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/developmentimage has the ray source code included and is setup for development.The
rayproject/examplesimage 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.
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