●Change8

Migrating to Ray ray-2.50.0

Version ray-2.50.0 introduces 1 breaking change. This guide details how to update your code.

Released: 10/10/2025

1
Breaking Changes
10
Migration Steps
27
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

ray.data.Dataset.explainray.data.Dataset.streaming_train_test_splitray.data.Dataset.max_task_concurrencyray.data.Dataset.zipray.data.writeray.data.Dataset.shuffleray.data.Dataset.joinray.data.Dataset.groupbyray.data.Dataset.mapray.train.reportray.train.get_all_reported_checkpointsray.train.checkpoint_upload_moderay.train.checkpoint_upload_functionray.train.validate_functionray.train.validate_configray.serve.AsyncInferenceAPIray.serve.replica_rankray.serve.FastAPIFactoryray.serve.RAY_SERVE_THROUGHPUT_OPTIMIZEDray.core.tensor_transportray.rllib.env.StepFailedRecreateEnvray.data.expressions.with_columnray.data.expressions.column_aliasray.data.expressions.downloadray.data.expressions.filterray.data.expressions.projectray.data.expressions.aggregate

Breaking Changes

●Issue #1

The default shuffle strategy for Ray Data has changed from sort‑based to hash‑based, which may alter the order of shuffled data; update any logic that relied on the previous ordering or explicitly set the shuffle strategy to sort‑based if needed.

Migration Steps

  1. 1
    If your code relied on the previous sort‑based shuffle ordering, explicitly set shuffle_strategy="sort" when calling Ray Data shuffle APIs.
  2. 2
    To use the new Direct Transport, add the tensor_transport parameter to the relevant Ray Core object creation calls.
  3. 3
    Update any custom write pipelines to accept iterators instead of expecting in‑memory block collections.
  4. 4
    Adjust any concurrency configurations that previously used a single integer to the new tuple format if needed.
  5. 5
    Review checkpointing code and replace old checkpoint upload mechanisms with the new checkpoint_upload_mode, checkpoint_upload_function, validate_function, and validate_config parameters in ray.train.report.
  6. 6
    If you use Ray Serve async inference, import and use the new async APIs and configure message brokers or DLQ as required.
  7. 7
    Enable throughput optimizations in Ray Serve by setting the RAY_SERVE_THROUGHPUT_OPTIMIZED environment variable.
  8. 8
    For Ray Train local mode, set num_workers=0 or use torchrun as documented.
  9. 9
    Replace any direct usage of the old GPU object transport with the new tensor_transport workflow.
  10. 10
    Check for the new StepFailedRecreateEnv exception in RLLib environments and update error handling accordingly.

Release Summary

This release adds major enhancements across Ray Data, Core, Train, Serve, and RLLib, including a new hash‑based shuffle, expression API, multi‑node LLM support, Direct Transport for GPU data, async inference in Serve, and extensive performance and memory optimizations.

Need More Details?

View the full release notes and all changes for Ray ray-2.50.0.

View Full Changelog