Registry / ai-ml / ray
library2.58.0pypypi✓ verified 27d ago

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
INSTALL
IMPORT
SIG · RAY
R
ray
ai-mlpythonv2.58.0
Install
22.7s avg
Import
1453ms
Disk
819MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.58.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
build_error
glibc
py 3.103.910 runs
installs and imports cleanly · install 22.7s · import 1.453s · 812MB
819MB installed
● package 819MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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.")
ray --version
Debug
Known issues
breakingRay 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`).
affects: >=2.52.0
breakingRay 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.
affects: >=2.56.0 (planned)
breakingRay 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`.
affects: >=2.51.0
gotchaIn 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.
affects: >=2.50.0
gotchaRay 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.
affects: >=2.52.0
breakingThe `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.
affects: >=2.2.0
breakingInstalling 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.
affects: * (when used with Python 3.13)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ray.tune'
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).
ConnectionRefusedError: [Errno 111] Connection refused
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.
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.
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.
AttributeError: module 'ray' has no attribute 'get'
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.
Upgrade
Version history
2.58.0latest on PyPI · released Aug 23, 2026
Audit
Dependencies
PythonrequiredRay requires Python 3.10 or newer. Support for Python 3.9 was dropped in Ray 2.52.0.
Agent activity
45 hits · last 30 days
node
38
OpenAI (training)
1
Resources