Ray Distributed Framework

raw JSON →
2.54.1 verified Tue May 12 auth: no python install: draft quickstart: stale

Ray is a unified open-source framework for building and scaling distributed applications and AI workloads in Python. It provides simple APIs for parallelizing Python functions and classes (tasks and actors) and a toolkit of specialized libraries (Ray Data, Train, Tune, Serve, RLlib) for machine learning. Ray offers a universal compute layer for orchestrating clusters, scheduling processes, fault tolerance, and autoscaling. The project maintains a very frequent release cadence, with minor and patch releases occurring every few weeks.

pip install ray
error ModuleNotFoundError: No module named 'ray.tune'
cause A specific optional Ray component (e.g., Tune, Train, Serve, RLlib, Data) was not installed, only the base `ray` package.
fix
Install the required component using pip: pip install "ray[tune]" (replace tune with the specific component needed).
error ConnectionRefusedError: [Errno 111] Connection refused
cause The Ray head node process is not running, or the client is attempting to connect to an incorrect or unreachable IP address/port.
fix
Ensure ray start --head is running on the head node, verify the --address used in ray.init() is correct, and check firewall settings.
error ValueError: The Ray cluster is not running. Please run `ray start --head` on the head node or pass an `address` to `ray.init()` that specifies a running cluster.
cause Ray's `ray.init()` was called with `address='auto'` or an explicit address, but no Ray cluster was found running or reachable at the specified location.
fix
Start a Ray cluster using ray start --head before attempting to connect, or explicitly set address=None (default) in ray.init() to start a local Ray instance if no external cluster is intended.
error AttributeError: module 'ray' has no attribute 'get'
cause Ray's core functionalities like `ray.get()`, `ray.put()`, `ray.wait()`, or `@ray.remote` are being used before `ray.init()` has been called to initialize the Ray runtime.
fix
Add ray.init() at the beginning of your script or program before using any Ray functions.
breaking Ray 2.52.0 (released in early 2026) officially ended support for Python 3.9. Users on Python 3.9 must upgrade to Python 3.10 or newer to use current and future Ray versions.
fix Upgrade your Python environment to 3.10 or higher (e.g., `conda install python=3.10` or `pyenv install 3.10.13`).
breaking Ray plans to drop support for Pydantic V1 starting with version 2.56.0. If your project uses Pydantic V1, you will need to migrate to Pydantic V2 to remain compatible with Ray.
fix Upgrade Pydantic to V2 (`pip install -U pydantic`) and update your code to use Pydantic V2 APIs. Consult the Pydantic migration guide and Ray's RFC on this change.
breaking Ray Train V2 is now enabled by default starting from Ray 2.51.0. This introduces significant API changes and improvements, particularly affecting the `Trainer.restore` API. Existing Ray Train users should consult the migration guide.
fix Review the Ray Train V2 Migration Guide (issues #49454 and REP) to adapt your training scripts. You can temporarily disable V2 by setting the environment variable `RAY_TRAIN_V2_ENABLED=0`.
gotcha In Ray Data 2.50.0, the default shuffle strategy for aggregations changed from sort-based to hash-based. While intended for lower memory usage and improved performance, this might alter behavior or performance characteristics if you relied on the previous sort-based default.
fix If unexpected behavior or performance issues arise with Ray Data aggregations, you may need to explicitly configure the shuffle strategy to `ray.data.DataContext.get_current().shuffle_strategy = ShuffleStrategy.SORT_SHUFFLE_PULL_BASED` or re-evaluate your data pipeline.
gotcha Ray includes built-in token authentication for enhanced security across its components (dashboard, CLI, API clients, internal services). However, this feature is initially off by default and requires explicit configuration to enable.
fix For production deployments, enable token authentication as per Ray's security documentation to prevent unauthorized access and code execution.
breaking The `ray.get_dashboard_url()` API has been removed. This function was deprecated in Ray 2.0 and is no longer available in current versions.
fix Remove calls to `ray.get_dashboard_url()`. The dashboard URL is typically printed in the logs when Ray starts (e.g., '127.0.0.1:8265') or can be retrieved from the `ray.init()` return value if available.
breaking Installing Ray on Python 3.13 is currently not supported, as official wheels may not be available on PyPI for this bleeding-edge Python version or the alpine distribution. This leads to `pip` failing to find any matching distribution.
fix Downgrade your Python environment to an officially supported version (e.g., Python 3.9, 3.10, 3.11, or 3.12 for current Ray versions). Check Ray's official documentation for supported Python versions and platform requirements.
pip install "ray[data,train,tune,serve,rllib]"
python os / libc variant status wheel install import disk
3.10 alpine (musl) data,train,tune,serve,rllib build_error - - - -
3.10 alpine (musl) ray build_error - - - -
3.10 alpine (musl) data,train,tune,serve,rllib - - - -
3.10 alpine (musl) ray - - - -
3.10 slim (glibc) data,train,tune,serve,rllib wheel 35.5s 1.39s 783M
3.10 slim (glibc) ray wheel 9.3s 1.26s 243M
3.10 slim (glibc) data,train,tune,serve,rllib - - 1.15s 771M
3.10 slim (glibc) ray - - 1.16s 238M
3.11 alpine (musl) data,train,tune,serve,rllib build_error - - - -
3.11 alpine (musl) ray build_error - - - -
3.11 alpine (musl) data,train,tune,serve,rllib - - - -
3.11 alpine (musl) ray - - - -
3.11 slim (glibc) data,train,tune,serve,rllib wheel 32.0s 2.08s 822M
3.11 slim (glibc) ray wheel 8.6s 1.91s 256M
3.11 slim (glibc) data,train,tune,serve,rllib - - 1.76s 810M
3.11 slim (glibc) ray - - 1.80s 251M
3.12 alpine (musl) data,train,tune,serve,rllib build_error - - - -
3.12 alpine (musl) ray build_error - - - -
3.12 alpine (musl) data,train,tune,serve,rllib - - - -
3.12 alpine (musl) ray - - - -
3.12 slim (glibc) data,train,tune,serve,rllib wheel 28.6s 2.11s 804M
3.12 slim (glibc) ray wheel 8.1s 2.10s 246M
3.12 slim (glibc) data,train,tune,serve,rllib - - 2.23s 792M
3.12 slim (glibc) ray - - 2.09s 241M
3.13 alpine (musl) data,train,tune,serve,rllib build_error - - - -
3.13 alpine (musl) ray build_error - - - -
3.13 alpine (musl) data,train,tune,serve,rllib - - - -
3.13 alpine (musl) ray - - - -
3.13 slim (glibc) data,train,tune,serve,rllib wheel 28.4s 1.96s 801M
3.13 slim (glibc) ray wheel 8.3s 2.06s 244M
3.13 slim (glibc) data,train,tune,serve,rllib - - 2.09s 789M
3.13 slim (glibc) ray - - 2.13s 239M
3.9 alpine (musl) data,train,tune,serve,rllib build_error - - - -
3.9 alpine (musl) ray build_error - - - -
3.9 alpine (musl) data,train,tune,serve,rllib - - - -
3.9 alpine (musl) ray - - - -
3.9 slim (glibc) data,train,tune,serve,rllib wheel 39.7s 1.41s 767M
3.9 slim (glibc) ray wheel 10.2s 1.39s 231M
3.9 slim (glibc) data,train,tune,serve,rllib - - 1.27s 764M
3.9 slim (glibc) ray - - 1.30s 230M

This quickstart demonstrates basic Ray Core usage, including initializing Ray, defining remote functions (tasks) using the `@ray.remote` decorator, launching these tasks with `.remote()`, and retrieving results with `ray.get()`. It includes an example of parallel execution with simulated delay.

import ray
import time
import os

# Initialize Ray (connects to an existing cluster or starts a local one)
# For a cluster, you might use ray.init(address="auto") or specify an address.
# For local testing, ray.init() is sufficient.
ray.init(address=os.environ.get('RAY_ADDRESS', None), ignore_reinit_error=True)

@ray.remote
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci.remote(n - 1) + fibonacci.remote(n - 2)

@ray.remote
def slow_square(x):
    time.sleep(1) # Simulate a slow computation
    return x * x

if __name__ == '__main__':
    print("--- Ray Tasks Example ---")
    # Run tasks in parallel
    futures = [slow_square.remote(i) for i in range(5)]
    results = ray.get(futures)
    print(f"Results from slow_square: {results}")

    # Example of recursive Ray tasks (note: fibonacci is a common but inefficient example for Ray's overhead)
    # For larger N, this can quickly create too many tasks.
    # result_fib = ray.get(fibonacci.remote(10))
    # print(f"Fibonacci(10) using Ray: {result_fib}")

    print("Ray initialized successfully, dashboard at:", ray.get_dashboard_url())

    ray.shutdown()
    print("Ray shutdown.")