安装 Ray#

Run Quickstart on Anyscale

Ray 目前官方支持 Linux 上的 x86_64、aarch64 (ARM) 以及 Apple Silicon (M1) 硬件。Windows 上的 Ray 目前处于 Beta 测试阶段。

官方发布#

从 Wheels 安装#

您可以通过选择最适合您用例的选项，在 Linux、Windows 和 macOS 上从 PyPI 安装最新官方版本的 Ray。

适用于机器学习应用

pip install -U "ray[data,train,tune,serve]"

# For reinforcement learning support, install RLlib instead.
# pip install -U "ray[rllib]"

适用于通用 Python 应用

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"

命令

已安装组件

pip install -U "ray"

核心

pip install -U "ray[default]"

核心、Dashboard、Cluster Launcher

pip install -U "ray[data]"

核心、Data

pip install -U "ray[train]"

核心、Train

pip install -U "ray[tune]"

核心、Tune

pip install -U "ray[serve]"

核心、Dashboard、Cluster Launcher、Serve

pip install -U "ray[serve-grpc]"

核心、Dashboard、Cluster Launcher、带 gRPC 支持的 Serve

pip install -U "ray[rllib]"

核心、Tune、RLlib

pip install -U "ray[all]"

核心、Dashboard、Cluster Launcher、Data、Train、Tune、Serve、RLlib。此选项不推荐。请如下方所示指定您需要的 extras。

提示

您可以组合安装 extras。例如，要安装包含 Dashboard、Cluster Launcher 和 Train 支持的 Ray，您可以运行

pip install -U "ray[default,train]"

每日发布 (Nightlies)#

您可以通过以下链接安装 nightly Ray wheels。这些每日发布版本经过自动化测试，但未经过完整的发布流程。要安装这些 wheels，请使用以下 pip 命令和 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)

Linux Python 3.10 (x86_64)

Linux Python 3.10 (aarch64)

Linux Python 3.11 (x86_64)

Linux Python 3.11 (aarch64)

Linux Python 3.12 (x86_64)

Linux Python 3.12 (aarch64)

Linux Python 3.13 (x86_64) (beta)

Linux Python 3.13 (aarch64) (beta)

MacOS (arm64)

MacOS Python 3.10 (arm64)

MacOS Python 3.11 (arm64)

MacOS Python 3.12 (arm64)

MacOS Python 3.13 (arm64) (beta)

Windows (beta)

Windows Python 3.10 (amd64)

Windows Python 3.11 (amd64)

Windows Python 3.12 (amd64)

注意

在 Windows 上，多节点 Ray 集群的支持目前仍处于实验阶段且未经测试。如果您遇到问题，请在 ray-project/ray#issues 提交报告。

注意

针对 nightly wheels，默认启用（可以 禁用）使用统计 数据收集，包括通过 ray.init() 启动的本地集群以及通过 CLI 启动的远程集群。

从特定提交安装#

您可以使用以下模板安装 master 分支上任何特定提交的 Ray wheels。您需要指定提交哈希、Ray 版本、操作系统和 Python 版本。

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

例如，这是针对 Python 3.10、macOS、提交 4f2ec46c3adb6ba9f412f09a9732f436c4a5d0c9 的 Ray 3.0.0.dev0 wheels。

pip install https://s3-us-west-2.amazonaws.com/ray-wheels/master/4f2ec46c3adb6ba9f412f09a9732f436c4a5d0c9/ray-3.0.0.dev0-cp310-cp310-macosx_12_0_arm64.whl

Wheel 文件名的格式存在细微差异；最好与 Nightlies 部分 中 URL 的格式进行匹配。以下是差异的摘要：

  • 对于 MacOS x86_64，在 2021 年 8 月 7 日之前的提交，文件名将包含 macosx_10_13 而非 macosx_10_15。

  • 对于 MacOS x86_64，在 2025 年 6 月 1 日之前的提交，文件名将包含 macosx_10_15 而非 macosx_12_0。

M1 Mac (Apple Silicon) 支持#

Ray 支持运行 Apple Silicon (例如 M1 Mac) 的机器。多节点集群未经测试。开始本地 Ray 开发：

  1. 安装 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 # 清理。

  2. 确保您使用的是 miniforge 环境（您的终端应显示 (base)）。

    • source ~/.bash_profile

    • conda activate

  3. 像往常一样安装 Ray。

    • pip install ray

Windows 支持#

Windows 支持处于 Beta 阶段。Ray 支持在 Windows 上运行，但存在以下限制（只有第一个是 Ray 特有的，其余在任何使用 Windows 的地方都适用）：

  • 多节点 Ray 集群未经测试。

  • 在 Windows 上，文件名处理比较棘手， Ray 可能仍然假设使用类 UNIX 的文件名而不是 Windows 文件名。这在下游软件包中也可能出现。

  • 在 Windows 上的性能已知较慢，因为在 Windows 上打开文件的速度比在其他操作系统上慢得多。这会影响日志记录。

  • Windows 没有写时复制的 fork 模型，因此启动新进程可能需要更多内存。

将您遇到的任何问题提交到 GitHub。

在 Arch Linux 上安装 Ray#

注意：Project Ray 的开发者并未测试在 Arch Linux 上安装 Ray。

Ray 可通过 Arch 用户仓库 (AUR) 作为 python-ray 在 Arch Linux 上使用。

您可以通过遵循 Arch Wiki 上的说明手动安装该软件包，或者使用 AUR 助手（例如 yay，推荐以简化安装）如下所示：

yay -S python-ray

要讨论与此软件包相关的任何问题，请参阅 AUR 页面 python-ray 的评论部分，在此处。

从 conda-forge 安装#

Ray 也可以作为 conda 包在 Linux 和 Windows 上安装。

# also works with mamba
conda create -c conda-forge python=3.10 -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

要安装 Ray 库，请使用如上所示的 pip 或 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

有关 Conda-forge 上所有可用的 ray 库的完整列表，请查看 https://anaconda.org/conda-forge/ray-default。

注意

Ray conda 包由社区维护，而非 Ray 团队。在使用 conda 环境时，建议在新建的环境中通过 pip install ray 从 PyPi 安装 Ray。

从源码构建 Ray#

对于大多数 Ray 用户来说，通过 pip 安装应该足够了。

但是，如果您需要从源码构建，请遵循 这些构建 Ray 的说明。

Docker 源码镜像#

用户可以从 rayproject/ray Docker Hub 仓库拉取 Docker 镜像。这些镜像包含 Ray 和所有必需的依赖项。它自带 anaconda 和各种版本的 Python。

镜像使用 tagged 格式 {Ray version}[-{Python version}][-{Platform}]。 Ray version 标签可以是以下之一：

Ray 版本标签

描述

latest

最新发布的 Ray。

x.y.z

特定的 Ray 版本，例如 2.31.0

nightly

最新开发的 Ray 构建（来自 Github master 的最近提交）

可选的 Python version 标签指定了镜像中的 Python 版本。Ray 支持的所有 Python 版本都可用，例如 py310、py311 和 py312。如果未指定，标签指向 Ray 版本支持的最低 Python 版本的镜像。

可选的 Platform 标签指定了镜像的目标平台：

平台标签

描述

-cpu

这些基于 Ubuntu 镜像。

-cuXX

这些基于 NVIDIA CUDA 镜像，并带有指定的 CUDA 版本。它们需要 NVIDIA Docker Runtime。

-gpu

指向特定 -cuXX 标记镜像的别名。

<no tag>

指向 -cpu 标记镜像的别名。

例如：对于基于 Python 3.10 且无 GPU 支持的 nightly 镜像，其标签为 nightly-py310-cpu。

如果您想在本地调整这些镜像的某些方面并构建它们，请参考以下脚本：

cd ray
./build-docker.sh

通过列出镜像来查看镜像

docker images

输出应类似于以下内容：

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

在 Docker 中启动 Ray#

首先启动部署容器。

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

将 <shm-size> 替换为适合您系统的限制，例如 512M 或 2G。一个好的估算是使用您可用内存的大约 30%（这是 Ray 内部用于其对象存储的部分）。这里的 -t 和 -i 选项对于支持容器的交互式使用是必需的。

如果您使用的是 GPU 版本 Docker 镜像，请记住在以下命令中添加 --gpus all 选项。将 <ray-version> 替换为您目标 Ray 版本。

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

注意： Ray 需要大量的共享内存，因为每个对象存储都将其所有对象保留在共享内存中，因此共享内存的大小将限制对象存储的大小。

您现在应该看到一个类似于以下的提示符：

root@ebc78f68d100:/ray#

测试安装是否成功#

要测试安装是否成功，请尝试运行一些测试。这假设您已克隆 git 仓库。

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

已安装的 Python 依赖项#

我们的 Docker 镜像预装了 Ray 及其库所需的 Python 依赖项。

我们为 Python 3.9 发布了 `ray` Docker 镜像中安装的依赖项。

Ray 版本：2.53.0（0de2118）

adlfs==2023.8.0
aiohappyeyeballs==2.6.1
aiohttp==3.11.16
aiohttp-cors==0.7.0
aiosignal==1.3.1
amqp==5.3.1
annotated-doc==0.0.4
annotated-types==0.6.0
anyio==3.7.1
archspec @ file:///home/conda/feedstock_root/build_artifacts/archspec_1737352602016/work
async-timeout==4.0.3
attrs==25.1.0
azure-common==1.1.28
azure-core==1.29.5
azure-datalake-store==0.0.53
azure-identity==1.17.1
azure-storage-blob==12.22.0
billiard==4.2.1
boltons @ file:///home/conda/feedstock_root/build_artifacts/boltons_1733827268945/work
boto3==1.29.7
botocore==1.32.7
Brotli @ file:///home/conda/feedstock_root/build_artifacts/brotli-split_1764016952863/work
cachetools==5.5.2
celery==5.5.3
certifi==2025.1.31
cffi @ file:///home/conda/feedstock_root/build_artifacts/cffi_1725560520483/work
charset-normalizer==3.3.2
click==8.1.7
click-didyoumean==0.3.1
click-plugins==1.1.1.2
click-repl==0.3.0
cloudpickle==2.2.0
colorama @ file:///home/conda/feedstock_root/build_artifacts/colorama_1733218098505/work
colorful==0.5.5
conda @ file:///home/conda/feedstock_root/build_artifacts/conda_1765816446718/work/conda-src
conda-libmamba-solver @ file:///home/conda/feedstock_root/build_artifacts/conda-libmamba-solver_1764081326783/work/src
conda-package-handling @ file:///home/conda/feedstock_root/build_artifacts/conda-package-handling_1736345463896/work
conda_package_streaming @ file:///home/conda/feedstock_root/build_artifacts/conda-package-streaming_1729004031731/work
cryptography==44.0.3
cupy-cuda12x==13.4.0
Cython==0.29.37
distlib==0.3.7
distro @ file:///home/conda/feedstock_root/build_artifacts/distro_1734729835256/work
dm-tree==0.1.8
exceptiongroup==1.3.1
Farama-Notifications==0.0.4
fastapi==0.121.0
fastrlock==0.8.3
filelock==3.17.0
flatbuffers==23.5.26
frozendict @ file:///home/conda/feedstock_root/build_artifacts/frozendict_1763082794572/work
frozenlist==1.4.1
fsspec==2023.12.1
google-api-core==2.24.2
google-api-python-client==2.111.0
google-auth==2.23.4
google-auth-httplib2==0.1.1
google-cloud-core==2.4.1
google-cloud-storage==2.14.0
google-crc32c==1.5.0
google-oauth==1.0.1
google-resumable-media==2.6.0
googleapis-common-protos==1.61.0
grpcio==1.74.0
gymnasium==1.1.1
h11==0.16.0
h2 @ file:///home/conda/feedstock_root/build_artifacts/h2_1733298745555/work
hpack @ file:///home/conda/feedstock_root/build_artifacts/hpack_1733299205993/work
httplib2==0.20.4
httptools==0.7.1
hyperframe @ file:///home/conda/feedstock_root/build_artifacts/hyperframe_1733298771451/work
idna==3.7
importlib-metadata==6.11.0
isodate==0.6.1
Jinja2==3.1.6
jmespath==1.0.1
jsonpatch @ file:///home/conda/feedstock_root/build_artifacts/jsonpatch_1733814567314/work
jsonpointer @ file:///home/conda/feedstock_root/build_artifacts/bld/rattler-build_jsonpointer_1765026384/work
jsonschema==4.23.0
jsonschema-specifications==2024.10.1
kombu==5.5.4
libmambapy @ file:///home/conda/feedstock_root/build_artifacts/bld/rattler-build_libmambapy_1764158555/work/libmambapy
linkify-it-py==2.0.3
lz4==4.4.5
markdown-it-py==2.2.0
MarkupSafe==2.1.3
mdit-py-plugins==0.3.5
mdurl==0.1.2
memray==1.19.1
menuinst @ file:///home/conda/feedstock_root/build_artifacts/menuinst_1765733081264/work
msal==1.28.1
msal-extensions==1.2.0b1
msgpack==1.0.7
multidict==6.0.5
numpy==1.26.4
opencensus==0.11.4
opencensus-context==0.1.3
opentelemetry-api==1.34.1
opentelemetry-exporter-prometheus==0.55b1
opentelemetry-proto==1.27.0
opentelemetry-sdk==1.34.1
opentelemetry-semantic-conventions==0.55b1
ormsgpack==1.7.0
packaging @ file:///home/conda/feedstock_root/build_artifacts/packaging_1733203243479/work
pandas==1.5.3
platformdirs==3.11.0
pluggy @ file:///home/conda/feedstock_root/build_artifacts/pluggy_1733222765875/work
portalocker==2.8.2
prometheus-client==0.19.0
prompt-toolkit==3.0.41
propcache==0.3.0
proto-plus==1.22.3
protobuf==4.25.8
psutil==5.9.6
py-spy==0.4.0
pyarrow==19.0.1
pyasn1==0.5.1
pyasn1-modules==0.3.0
pycosat @ file:///home/conda/feedstock_root/build_artifacts/pycosat_1757744612102/work
pycparser==2.21
pydantic==2.12.4
pydantic_core==2.41.5
Pygments==2.18.0
PyJWT==2.8.0
pyOpenSSL==25.0.0
pyparsing==3.1.1
PySocks @ file:///home/conda/feedstock_root/build_artifacts/pysocks_1733217236728/work
python-dateutil==2.8.2
python-dotenv==1.2.1
pytz==2022.7.1
PyYAML==6.0.3
ray @ file:///home/ray/ray-2.53.0-cp310-cp310-manylinux2014_x86_64.whl#sha256=ec758f5aa71f01f090557a0fe8732689f7e2f8e49a1f39f4649ee9a7804c7514
referencing==0.36.2
requests==2.32.5
rich==13.7.1
rpds-py==0.22.3
rsa==4.7.2
ruamel.yaml @ file:///home/conda/feedstock_root/build_artifacts/ruamel.yaml_1761160605807/work
ruamel.yaml.clib @ file:///home/conda/feedstock_root/build_artifacts/ruamel.yaml.clib_1760564169911/work
s3transfer==0.8.0
scipy==1.11.4
six==1.16.0
smart-open==6.2.0
sniffio==1.3.1
starlette==0.49.1
tensorboardX==2.6.2.2
textual==4.0.0
tqdm @ file:///home/conda/feedstock_root/build_artifacts/tqdm_1735661334605/work
truststore @ file:///home/conda/feedstock_root/build_artifacts/truststore_1729762363021/work
typing-inspection==0.4.2
typing_extensions==4.15.0
tzdata==2025.2
uc-micro-py==1.0.3
uritemplate==4.1.1
urllib3==1.26.19
uvicorn==0.22.0
uvloop==0.21.0
vine==5.1.0
virtualenv==20.29.1
watchfiles==0.19.0
wcwidth==0.2.13
websockets==11.0.3
yarl==1.18.3
zipp==3.19.2
zstandard==0.25.0

使用 Maven 安装 Ray Java#

注意

所有 Ray Java API 均处于实验阶段，仅由社区支持。

在使用 Maven 安装 Ray Java 之前，您应该使用 pip install -U ray 安装 Ray Python。请注意，Ray Java 和 Ray Python 的版本必须匹配。如果您想安装 Ray Java 快照版本，还需要 nightly Ray python wheels。

在 中央仓库 中查找最新的 Ray Java 版本。要在您的应用程序中使用最新的 Ray Java 版本，请在您的 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>

最新的 Ray Java 快照可以在 sonatype 仓库 中找到。要在您的应用程序中使用最新的 Ray Java 快照，请在您的 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>

注意

当您运行 pip install 来安装 Ray 时，Java jar 也会被安装。上述依赖项仅用于构建您的 Java 代码并在本地模式下运行您的代码。

如果您想在多节点 Ray 集群中运行 Java 代码，最好在打包代码时排除 Ray jar，以避免 jar 冲突（如果版本不匹配 - 通过 pip install 安装的和 Maven 依赖项）。

安装 Ray C++#

注意

所有 Ray C++ API 均处于实验阶段，仅由社区支持。

您可以如下安装和使用 Ray C++ API。

pip install -U ray[cpp]

# Create a Ray C++ project template to start with.
ray cpp --generate-bazel-project-template-to ray-template

注意

如果您从源码构建 Ray，请在运行应用程序之前从文件 cpp/example/.bazelrc 中删除构建选项 build --cxxopt="-D_GLIBCXX_USE_CXX11_ABI=0"。相关问题是 这个。