Pydantic v2.14 发布：支持 Python 3.15、惰性导入与 TypeForm

Pydantic v2.14 was released on October 8th. You can install it now from PyPI:

This release features the work of 13 external contributors and provides various new features, performance improvements, and bug fixes. Several minor changes (considered non-breaking changes according to our versioning policy) are also included in this release. Make sure to look into them before upgrading.

This release drops support for Python 3.9 and adds support for Python 3.15.

Highlights include:

Stabilized MISSING sentinel; Support for lazy imports; Support for TypeForm

You can see the full changelog on GitHub.

#Quick Reference

New Features; Changes; Performance

Building agents in production?

See what they're actually doing with Logfire — traces, evals, cost, and behavior in one view.

#New Features

Pydantic 2.14 officially supports Python 3.15, including most of the new features it introduces. These are covered first.

#Stabilized MISSING sentinel

The MISSING sentinel, added as an experimental feature in 2.12, is now stabilized and part of the main Pydantic API.

MISSING is a singleton indicating that a field value was not provided during validation. During serialization, any field with MISSING as a value is excluded from the output.

Static type checkers support MISSING starting from pyright 1.1.414 and Mypy 2.4.

PR reference: #13782.

#Support for lazy imports

Lazy imports were introduced by PEP 810 in Python 3.15.

Lazy imports let models in separate modules reference each other without running into cyclic imports:

a.py:

b.py:

See the documentation for more details.

PR reference: #13776.

#Support for TypeForm

typing.TypeForm was introduced by PEP 747 in Python 3.15, and is supported by major static type checkers.

Pydantic now uses TypeForm in a number of places, in particular with TypeAdapter:

Type checkers now infer the correct type for any type form passed to Pydantic (x | y unions, Annotated[...] forms, etc.), not just classes.

Static type checkers support TypeForm starting from pyright 1.1.412 and Mypy 2.2.

PR reference: #13459.

#Support for frozendict

The frozendict type was introduced by PEP 814 in Python 3.15. Pydantic supports it, and it validates and serializes like a regular dict. See the documentation for more details.

PR reference: #13634.

#__namespace__ argument for create_model()

create_model() now accepts a __namespace__ argument, to add any attribute to the class namespace of the created model, such as validators, methods or computed fields:

The existing __validators__ argument is limited to validators. It is now recommended to use __namespace__ instead, as __validators__ will be deprecated in v3.

PR reference: #13895.

#New core schema types

Several supported types now have their own core schema, meaning they are natively validated/serialized by the pydantic-core Rust component. Previously, Pydantic defined custom Python validators for them, which were slower and didn't support constraints.

The following types were migrated:

fractions.Fraction in #13339. ZeroDivisionErrors during validation are now properly handled; Named tuples in #13505. This fixes a number of issues related to validation; collections.deque in #13757; collections.OrderedDict in #13796; collections.Counter in #13824

#Changes

This release contains some minor changes that may affect existing code. Make sure to go through them before upgrading.

#JSON Schema changes

This release introduces a number of JSON Schema changes that may affect your generated model schemas.

Decimal pattern

In 2.12, #11987 added regex patterns in the JSON Schema for Decimal types. This caused a number of issues, as some users define validation contracts based on the generated schema.

For this reason, the pattern is no longer included by default. A custom GenerateJsonSchema subclass can be defined to enable the pattern again (see the documentation for more details).

PR reference: #13672.

TypeAdapter config

The configuration of the TypeAdapter is now used when generating the JSON Schema:

PR reference: #13676.

Other JSON Schema changes

These changes are mostly bug fixes that make the JSON Schema more consistent with the validation/serialization behavior:

Don't apply serialization temporal formats to validation JSON Schemas in #13711; Reflect str_min_length and str_max_length config in the JSON Schema in #13714; Use the field name in validation JSON Schemas when validate_by_alias is False in #13717; Fix config propagation of stdlib dataclasses and TypedDicts in JSON Schema in #13891; Don't apply ser_json_timedelta to all datetime types in serialization inference in #13892; Encode JSON Schema defaults with a consistent configuration in #13893

#model_config is no longer mutated

Prior to 2.14, the model_config attribute could be mutated by Pydantic, e.g. to populate values from deprecated settings. This is no longer the case: model_config will always reflect what was set by the user (merged with the configuration of parent classes):

PR reference: #13825.

#Model signature with validate_by_alias=False

When validate_by_alias is set to False, the generated __signature__ of models and Pydantic dataclasses now uses the field name instead of the alias, matching what validation actually accepts:

Contributed by @jaideeppyne. PR reference: #13730.

#multiple_of constraint

Using a non-positive value for multiple_of now raises an error when the model is defined. Previously, an unhandled runtime exception was raised during validation.

PR reference: #13862.

#Numeric constraints in the pipeline API

In the experimental pipeline API, numeric constraints (gt(), ge(), lt(), le() and multiple_of()) are now always applied natively by pydantic-core on numeric types. Previously, some of them were applied as Python validators, e.g. when chaining several constraints or when the constraint value didn't match the validated type. As a result, these constraints are now included in the JSON Schema, and validation errors are the same as for regular fields:

PR reference: #13516.

#Invalid index_key in wrap serializers

The handler of wrap serializers takes an optional second index_key argument, which must be an integer or a string. A previous docstring example wrongly passed the info argument instead, which went unnoticed unless include or exclude was used. Such invalid values now raise an explicit error:

If you copied this pattern, remove the second argument when calling the handler.

PR reference: #13506.

#Performance

2.14 includes several optimizations to schema generation. Most of them individually reduce model build time by 5–20% on our benchmarks, which adds up at import time for applications that define many models:

Optimize type lookup logic in core schema generation in #13573; Refactor type references logic in #13643; Move schema gathering logic to pydantic-core in #13725; Improve performance of FieldInfo construction in #13726; Improve performance of GenerateSchema.generate_schema() dispatching in #13614; Avoid exponential core schema traversal in gather_schemas_for_cleaning() in #13523; Introduce micro-optimizations for model class building in #13540

Ready to try the new features? Upgrade now with pip install --upgrade pydantic or uv add --upgrade pydantic and check out the full release notes. Have questions or feedback? Join the conversation on our community Slack.