Installing Ray#
Ray currently officially supports x86_64, aarch64 (ARM) for Linux, and Apple silicon (M1) hardware. Ray on Windows is currently in beta.
Official Releases#
From Wheels#
You can install the latest official version of Ray from PyPI on Linux, Windows, and macOS by choosing the option that best matches your use case.
For machine learning applications
pip install -U "ray[data,train,tune,serve]"
# For reinforcement learning support, install RLlib instead.
# pip install -U "ray[rllib]"
For general Python applications
pip install -U "ray[default]"
# If you don't want Ray Dashboard or Cluster Launcher, install Ray with minimal dependencies instead.
# pip install -U "ray"
Command |
Installed components |
---|---|
|
Core |
|
Core, Dashboard, Cluster Launcher |
|
Core, Data |
|
Core, Train |
|
Core, Tune |
|
Core, Dashboard, Cluster Launcher, Serve |
|
Core, Dashboard, Cluster Launcher, Serve with gRPC support |
|
Core, Tune, RLlib |
|
Core, Dashboard, Cluster Launcher, Data, Train, Tune, Serve, RLlib |
Tip
You can combine installation extras. For example, to install Ray with Dashboard, Cluster Launcher, and Train support, you can run:
pip install -U "ray[default,train]"
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 (x86_64) |
Linux (arm64/aarch64) |
---|---|
MacOS (x86_64) |
MacOS (arm64) |
---|---|
Note
On Windows, support for multi-node Ray clusters is currently experimental and untested. If you run into issues please file a report at 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.
Note
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}-{OS_VERSION}.whl
For example, here are the Ray 3.0.0.dev0 wheels for Python 3.9, MacOS for commit 4f2ec46c3adb6ba9f412f09a9732f436c4a5d0c9
:
pip install https://s3-us-west-2.amazonaws.com/ray-wheels/master/4f2ec46c3adb6ba9f412f09a9732f436c4a5d0c9/ray-3.0.0.dev0-cp39-cp39-macosx_10_15_x86_64.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 MacOS, commits predating August 7, 2021 will have
macosx_10_13
in the filename instead ofmacosx_10_15
.
M1 Mac (Apple Silicon) Support#
Ray supports machines running Apple Silicon (such as M1 macs). Multi-node clusters are untested. To get started with local Ray development:
Install miniforge.
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh
bash Miniforge3-MacOSX-arm64.sh
rm Miniforge3-MacOSX-arm64.sh # Cleanup.
Ensure you’re using the miniforge environment (you should see (base) in your terminal).
source ~/.bash_profile
conda activate
Install Ray as you normally would.
pip install ray
Windows Support#
Windows support is in Beta. Ray supports running on Windows with the following caveats (only the first is Ray-specific, the rest are true anywhere Windows is used):
Multi-node Ray clusters are untested.
Filenames are tricky on Windows and there still may be a few places where Ray assumes UNIX filenames rather than Windows ones. This can be true in downstream packages as well.
Performance on Windows is known to be slower since opening files on Windows is considerably slower than on other operating systems. This can affect logging.
Windows does not have a copy-on-write forking model, so spinning up new processes can require more memory.
Submit any issues you encounter to 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 From conda-forge#
Ray can also be installed as a conda package on Linux and Windows.
# also works with mamba
conda create -c conda-forge python=3.9 -n ray
conda activate ray
# Install Ray with support for the dashboard + cluster launcher
conda install -c conda-forge "ray-default"
# Install Ray with minimal dependencies
# conda install -c conda-forge ray
To install Ray libraries, use pip
as above or conda
/mamba
.
conda install -c conda-forge "ray-data" # installs Ray + dependencies for Ray Data
conda install -c conda-forge "ray-train" # installs Ray + dependencies for Ray Train
conda install -c conda-forge "ray-tune" # installs Ray + dependencies for Ray Tune
conda install -c conda-forge "ray-serve" # installs Ray + dependencies for Ray Serve
conda install -c conda-forge "ray-rllib" # installs Ray + dependencies for Ray RLlib
For a complete list of available ray
libraries on Conda-forge, have a look
at https://anaconda.org/conda-forge/ray-default
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#
Users can pull a Docker image from the rayproject/ray
Docker Hub repository.
The images include Ray and all required dependencies. It comes with anaconda and various versions of Python.
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. 2.31.0 |
nightly |
The most recent Ray development build (a recent commit from Github |
The optional Python version
tag specifies the Python version in the image. All Python versions supported by Ray are available, e.g. py39
, py310
and py311
. If unspecified, the tag points to an image of the lowest Python version that the Ray version supports.
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 |
<no tag> |
Aliases to |
Example: for the nightly image based on Python 3.9
and without GPU support, the tag is nightly-py39-cpu
.
If you want to tweak some aspects of these images and build them locally, refer to the following script:
cd ray
./build-docker.sh
Review images by listing them:
docker images
Output should look something like the following:
REPOSITORY TAG IMAGE ID CREATED SIZE
rayproject/ray dev 7243a11ac068 2 days ago 1.11 GB
rayproject/base-deps latest 5606591eeab9 8 days ago 512 MB
ubuntu 22.04 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
Installed Python dependencies#
Our docker images are shipped with pre-installed Python dependencies required for Ray and its libraries.
We publish the dependencies that are installed in our ray
Docker images for Python 3.9.
Ray version: 2.40.0 (22541c3)
aiohttp==3.9.5
aiohttp-cors==0.7.0
aiosignal==1.3.1
anaconda-anon-usage @ file:///croot/anaconda-anon-usage_1732732445543/work
annotated-types==0.6.0
anyio==3.7.1
archspec @ file:///croot/archspec_1709217642129/work
async-timeout==4.0.3
attrs==21.4.0
backoff==1.10.0
boltons @ file:///croot/boltons_1677628692245/work
boto3==1.26.76
botocore==1.29.76
Brotli @ file:///croot/brotli-split_1714483155106/work
cachetools==5.3.2
certifi==2023.11.17
cffi==1.16.0
charset-normalizer==3.3.2
click==8.1.7
cloudpickle==2.2.0
colorful==0.5.5
conda @ file:///home/conda/feedstock_root/build_artifacts/conda_1732552589799/work
conda-content-trust @ file:///croot/conda-content-trust_1714483159009/work
conda-libmamba-solver @ file:///croot/conda-libmamba-solver_1706733287605/work/src
conda-package-handling @ file:///croot/conda-package-handling_1731369017509/work
conda_package_streaming @ file:///croot/conda-package-streaming_1731366181659/work
cryptography==42.0.5
cupy-cuda12x==13.1.0
Cython==0.29.37
distlib==0.3.7
distro @ file:///croot/distro_1714488253808/work
dm-tree==0.1.8
exceptiongroup==1.2.2
Farama-Notifications==0.0.4
fastapi==0.109.2
fastrlock==0.8.2
filelock==3.13.1
flatbuffers==23.5.26
frozendict @ file:///croot/frozendict_1713194832637/work
frozenlist==1.4.1
fsspec==2023.5.0
google-api-core==1.34.0
google-api-python-client==2.111.0
google-auth==2.23.4
google-auth-httplib2==0.1.1
google-oauth==1.0.1
googleapis-common-protos==1.61.0
grpcio==1.66.2
gymnasium==1.0.0
h11==0.12.0
httplib2==0.20.4
httptools==0.6.4
idna @ file:///croot/idna_1714398848350/work
imageio==2.34.2
importlib-metadata==6.11.0
Jinja2==3.1.2
jmespath==1.0.1
jsonpatch @ file:///croot/jsonpatch_1714483231291/work
jsonpointer==2.1
jsonschema==4.17.3
lazy_loader==0.4
libmambapy @ file:///croot/mamba-split_1714483352891/work/libmambapy
lz4==4.3.3
markdown-it-py==2.2.0
MarkupSafe==2.1.3
mdurl==0.1.2
memray==1.10.0
menuinst @ file:///croot/menuinst_1731364904452/work
msgpack==1.0.7
multidict==6.0.5
networkx==3.2.1
numpy==1.26.4
opencensus==0.11.3
opencensus-context==0.1.3
opentelemetry-api==1.1.0
opentelemetry-exporter-otlp==1.1.0
opentelemetry-exporter-otlp-proto-grpc==1.1.0
opentelemetry-proto==1.1.0
opentelemetry-sdk==1.1.0
opentelemetry-semantic-conventions==0.20b0
packaging==23.0
pandas==1.5.3
pillow==10.3.0
platformdirs==3.11.0
pluggy @ file:///croot/pluggy_1733169602837/work
prometheus-client==0.19.0
protobuf==3.20.3
psutil==5.9.6
py-spy==0.3.14
pyarrow==14.0.2
pyasn1==0.5.1
pyasn1-modules==0.3.0
pycosat @ file:///croot/pycosat_1714510623388/work
pycparser @ file:///tmp/build/80754af9/pycparser_1636541352034/work
pydantic==2.5.0
pydantic_core==2.14.1
Pygments==2.18.0
pyOpenSSL==24.2.1
pyparsing==3.1.1
pyrsistent==0.20.0
PySocks @ file:///tmp/build/80754af9/pysocks_1605305812635/work
python-dateutil==2.8.2
python-dotenv==1.0.1
pytz==2022.7.1
PyYAML==6.0.1
ray @ file:///home/ray/ray-2.40.0-cp39-cp39-manylinux2014_x86_64.whl#sha256=ca6d3f9d50ca0be5b382ab3fe42a914136fe5204a43afff6b21069fdd0b37310
redis==4.4.2
requests==2.31.0
rich==13.3.2
rsa==4.7.2
ruamel.yaml @ file:///croot/ruamel.yaml_1727980156079/work
ruamel.yaml.clib @ file:///croot/ruamel.yaml.clib_1727769819935/work
s3transfer==0.6.2
scikit-image==0.24.0
scipy==1.11.4
shellingham==1.5.4
six==1.16.0
smart-open==6.2.0
sniffio==1.3.1
starlette==0.36.3
tensorboardX==2.6.2.2
tifffile==2024.7.21
tqdm @ file:///croot/tqdm_1724853939799/work
typer==0.12.3
typing_extensions==4.8.0
uritemplate==4.1.1
urllib3==1.26.19
uvicorn==0.22.0
uvloop==0.19.0
virtualenv==20.25.3
watchfiles==0.19.0
websockets==11.0.3
yarl==1.9.4
zipp==3.19.2
zstandard @ file:///croot/zstandard_1731356346222/work
Install Ray Java with Maven#
Note
All Ray Java APIs are experimental and only supported by the community.
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.
Find the latest Ray Java release in the 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.
Install Ray C++#
Note
All Ray C++ APIs are experimental and only supported by the community.
You can install and use Ray C++ API as follows.
pip install -U ray[cpp]
# Create a Ray C++ project template to start with.
ray cpp --generate-bazel-project-template-to ray-template
Note
If you build Ray from source, remove the build option build --cxxopt="-D_GLIBCXX_USE_CXX11_ABI=0"
from the file cpp/example/.bazelrc
before running your application. The related issue is this.