Version Policy

Pydantic AI V1 was released in September 2025. The first V2 beta (v2.0.0b1) was released on May 20, 2026, with a stable V2.0 expected within roughly two weeks; see the Upgrade Guide for what's in V2, how to install the beta, and how to upgrade.

We will not intentionally make breaking changes in minor releases. Functionality marked as deprecated in a release is not removed until the next major version, which we won't release sooner than 3 months after V2.0 ships stable. During the V2 beta, the V2 API and behaviors aren't yet covered by this guarantee — we don't expect major changes but may still adjust in response to feedback before the stable V2.0 release.

We'll continue to provide security fixes for V1 for at least 6 months after V2's stable release, so you have time to upgrade your applications. When you're ready to make the jump, the Upgrade Guide lists the breaking changes for each version, along with our recommended path to V2.

Of course, some apparently safe changes and bug fixes will inevitably break some users' code — obligatory link to xkcd.

The following changes will NOT be considered breaking changes, and may occur in minor releases:

• Bug fixes that may result in existing code breaking, provided that such code was relying on undocumented features/constructs/assumptions.
• Adding new message parts, stream events, or optional fields (including fields with default values) on existing message (part) and event types. Always code defensively when consuming message parts or event streams, and use the ModelMessagesTypeAdapter to (de)serialize message histories.
• Changing OpenTelemetry span attributes. Because different observability platforms support different versions of the OpenTelemetry Semantic Conventions for Generative AI systems, Pydantic AI lets you configure the instrumentation version, but the default version may change in a minor release. Span attributes for Pydantic Evals may also change as we iterate on Evals support in Pydantic Logfire.
• Changing how __repr__ behaves, even of public classes.

In all cases we will aim to minimize churn and do so only when justified by the increase of quality of Pydantic AI for users.

Beta Features

At Pydantic, we like to move quickly and innovate! To that end, minor releases may introduce beta features (indicated by a beta module) that are active works in progress. While in its beta phase, a feature's API and behaviors may not be stable, and it's very possible that changes made to the feature will not be backward-compatible. We aim to move beta features out of beta within a few months after initial release, once users have had a chance to provide feedback and test the feature in production.

Support for Python versions

Pydantic will drop support for a Python version when the following conditions are met:

• The Python version has reached its expected end of life.
• less than 5% of downloads of the most recent minor release are using that version.