●Change8

Migrating to Ray ray-2.51.0

Version ray-2.51.0 introduces 2 breaking changes. This guide details how to update your code.

Released: 10/29/2025

2
Breaking Changes
5
Migration Steps
11
Affected Symbols

⚠️ Check Your Code

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

ray.trainray.train.torch.get_deviceray.train.torch.iter_torch_batchesray.train.ControllerErrorray.train.ThreadRunnerray.train.JaxBackend.shutdownray.train.TrainingFailedErrorray.serve.AutoscalingContextray.serve.reconfigurevLLMEngineStageCheckpointManager

Breaking Changes

●Issue #1

Ray Train v2 is enabled by default; code that relies on Ray Train v1 behavior may break. Disable with environment variable RAY_TRAIN_V2_ENABLED=0 or migrate to the v2 APIs.

●Issue #2

Checkpoint Manager Pydantic API was reverted from v2 to v1; any user code importing or extending the v2 models must be updated to the v1 equivalents.

Migration Steps

  1. 1
    Review the Ray Train v2 migration guide (https://github.com/ray-project/ray/issues/49454) and update code to use the v2 APIs or set `RAY_TRAIN_V2_ENABLED=0` to retain v1 behavior.
  2. 2
    Replace any imports or usage of the Checkpoint Manager Pydantic v2 models with the v1 equivalents as indicated in the release notes.
  3. 3
    Update custom autoscaling policies in Ray Serve to use the new `AutoscalingContext` fields (`total_running_requests`, `total_queued_requests`, `total_num_requests`) and aggregation functions if needed.
  4. 4
    Adjust any code that relied on per‑deployment autoscaling to the new application‑level autoscaling model.
  5. 5
    Refresh documentation links and examples to reflect the new top‑level `ray.train` aliases.

Release Summary

This release introduces Ray Train v2 as the default, adds application‑level autoscaling to Ray Serve, and brings numerous new features and fixes to Ray Data, Train, Tune, and Serve.

Need More Details?

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

View Full Changelog