●Change8

Migrating to Ray ray-2.49.0

Version ray-2.49.0 introduces 4 breaking changes. This guide details how to update your code.

Released: 8/26/2025

4
Breaking Changes
6
Migration Steps
18
Affected Symbols

⚠️ Check Your Code

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

BatchMetadataAutoscalingContextAutoscalingPolicyPrefixCacheAffinityRouterLMCacheConnectorV1JaxTrainerTrainStateActorDEFAULT_OBJECT_STORE_MEMORY_LIMIT_FRACTIONtarget_shuffle_max_block_sizerandomize_blocksDEFAULT variables in Ray Train (e.g., DEFAULT_*)AutoscalingActorPoolStatsManagerBundleQueue.has_nextResourceManager.allocate_gpuStreamingSplitRayServeRouter (same event loop option)Async inference APIs (e.g., async get_current_servable_instance)

Breaking Changes

●Issue #1

Removed the randomize-blocks reorder rule, which may affect pipelines that relied on its previous ordering behavior.

●Issue #2

Removed the internal target_shuffle_max_block_size parameter, potentially impacting custom shuffle configurations.

●Issue #3

Converted Ray Train DEFAULT variables from strings to booleans, requiring updates to any code that compared them as strings.

●Issue #4

BatchMetadata now wraps batch indices; code accessing raw indices directly may need to be updated.

Migration Steps

  1. 1
    Update any code that relied on the randomize-blocks reorder rule to handle the new stable ordering.
  2. 2
    Remove references to target_shuffle_max_block_size; rely on automatic shuffle sizing.
  3. 3
    Adjust checks against Ray Train DEFAULT variables to compare against booleans instead of strings.
  4. 4
    Replace direct access to batch indices with the BatchMetadata APIs.
  5. 5
    If using custom autoscaling, adopt the new AutoscalingContext and AutoscalingPolicy classes.
  6. 6
    For Ray Serve LLM users, ensure vLLM version is >=0.10 or adjust configuration accordingly.

Release Summary

This release adds extensive performance enhancements, new features such as JaxTrainer, async inference, and custom autoscaling, while fixing numerous bugs; it also introduces a few breaking changes that may require migration steps.

Need More Details?

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

View Full Changelog