Ray Distributed Framework

2.54.1 · active · verified Sat Mar 28

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.

Warnings

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.

Install

pip install ray Base Installation
pip install "ray[data,train,tune,serve,rllib]" With Common ML Libraries

Imports

ray
```
import ray
```
Commonly imported as 'ray' for initialization and core functionalities.
remote
```
@ray.remote
```
Decorator used to convert Python functions into Ray tasks and Python classes into Ray actors for distributed execution.

Quickstart

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.")

view raw JSON →