[RFC] Drop Support for Pydantic v1 in Ray

[abrarsheikh]

Summary

This RPC proposes dropping support for Pydantic v1 in Ray and migrating all code to use Pydantic v2 native APIs. This will simplify the codebase, remove technical debt from the compatibility layer, and allow Ray to take advantage of Pydantic v2's performance improvements and modern features.

Motivation

Current State

Ray currently supports both Pydantic v1 and Pydantic v2 through a compatibility layer (ray._common.pydantic_compat). When Pydantic v2 is installed, Ray imports from pydantic.v1 to maintain backward compatibility. This approach has several drawbacks, but most prominent are Performance and Feature limitation.

Pydantic v1 End of Life

• Pydantic v1 has been superseded by v2 since June 2024
• Pydantic v2 has been stable for over 2 years
• The Python ecosystem has largely migrated to Pydantic v2
• Continued v1 support limits Ray's ability to adopt modern dependencies

Proposal

Migration Timeline

We propose a phased approach to dropping Pydantic v1 support:

Phase 1: Announcement (Ray 2.53)

• Send announcement to ray-dev mailing list about upcoming Pydantic v1 deprecation
• Update Ray documentation to mention Pydantic v2 requirement in future releases
• Add deprecation notice to release notes
• Add runtime check to emit clear error message if Pydantic v1 detected

Phase 2: Drop Support (Ray 2.56)

• Update setup.py to set pydantic version constraint: pydantic>=2.5,<3
• Update CI/CD pipelines to remove tests for Pydantic v1
• Communicate changes in release notes

Phase 3: Migrate Ray Code to v2 (Ray 2.59)

• Remove python/ray/_common/pydantic_compat.py compatibility layer
• Update all imports to use native Pydantic v2 APIs:
  • ray.serve components
  • ray.train components
  • ray.llm components
  • ray.util.state components
  • Core serialization code
• Remove all IS_PYDANTIC_2 conditional checks
• Update imports from pydantic.v1 to pydantic throughout codebase
• Remove dual-path test code that validates both v1 and v2
• Final release notes documenting completion of migration

References

• Pydantic v2 Migration Guide
• Pydantic v2 Release Announcement
• FastAPI and Pydantic v2

[abrarsheikh]

From Ray Serve's perspective, by switching to Pydantic V2, we can increase the serve controller iteration speed by 1.5x at least.