pydantic-core

Warnings

• breaking pydantic-core does NOT follow SemVer. Each pydantic-core version is pinned to exactly one pydantic version. Never pin or upgrade pydantic-core independently of pydantic — doing so will cause immediate ImportError or runtime crashes.
  Fix: Always install and upgrade pydantic, not pydantic-core directly. Let pydantic's dependency constraint select the correct pydantic-core version automatically.
• breaking The internal CoreSchema format (the dict structure produced by core_schema.*) is NOT considered stable API and may change between minor pydantic-core releases. Hardcoded CoreSchema dicts (without using core_schema builders) will silently break.
  Fix: Always use the core_schema builder functions (e.g. core_schema.str_schema(), core_schema.typed_dict_schema()) instead of hand-writing raw dicts. Never rely on __pydantic_core_schema__ dict structure being stable.
• breaking On platforms without a pre-built binary wheel (e.g. ARM musl/Alpine, exotic BSDs, very old macOS), pip falls back to building from source and requires a compatible Rust toolchain (rustc + cargo). The build will fail with 'can't find Rust compiler' or Cargo compile errors if Rust is absent or too old.
  Fix: Always install from a pre-built wheel: keep pip up to date (`pip install --upgrade pip`) so it can resolve manylinux/musllinux wheels. For Docker, use a glibc-based image (e.g. python:3.x-slim, not python:3.x-alpine) or install Rust before pip install.
• breaking Deploying to cross-compiled environments (e.g. AWS Lambda with --platform manylinux, Docker buildx for arm64) and building on a different host OS/arch causes 'No module named pydantic_core._pydantic_core' at runtime because the .so extension does not match the target platform ABI.
  Fix: Pass the correct --platform and --python-version flags to pip when building Lambda layers (e.g. `pip install --platform manylinux2014_x86_64 --only-binary=:all: pydantic-core`). Verify the .so suffix matches the target Python ABI using sysconfig.get_config_var('EXT_SUFFIX').
• breaking Pydantic V1 is not compatible with Python 3.14 or greater. pydantic-core (V2) is required for Python 3.14+ support.
  Fix: Migrate to pydantic V2 (which uses pydantic-core). The compatibility shim `from pydantic import v1 as pydantic_v1` is available for incremental migration.
• gotcha validate_json() on SchemaValidator is significantly faster than calling json.loads() followed by validate_python() because it avoids creating intermediate Python objects. Using validate_python(json.loads(data)) is a common performance mistake.
  Fix: Call v.validate_json(json_bytes_or_str) directly instead of v.validate_python(json.loads(json_bytes_or_str)).
• gotcha Importing from pydantic_core._pydantic_core (the private Rust extension module) instead of pydantic_core is unsupported. The private module's API surface can change without notice.
  Fix: Import only from `pydantic_core` (e.g. `from pydantic_core import SchemaValidator, core_schema, ValidationError`). The public API is documented at docs.pydantic.dev/latest/api/pydantic_core/.

Install

• pip install pydantic-core Install via pip (binary wheel, no Rust required)
• pip install pydantic Preferred: install via pydantic (pulls correct pydantic-core version automatically)

Imports

• SchemaValidator

  from pydantic_core import SchemaValidator

  Always import from the top-level pydantic_core package, not from the private _pydantic_core Rust extension module directly
• SchemaSerializer

  from pydantic_core import SchemaSerializer

  Python wrapper around the Rust serialization logic; use for custom standalone serializers
• ValidationError

  from pydantic_core import ValidationError

  Raised by SchemaValidator on invalid input; also re-exported from pydantic
• core_schema

  from pydantic_core import core_schema

  Module containing all schema builder functions (str_schema, int_schema, typed_dict_schema, etc.) used to construct CoreSchema dicts
• PydanticCustomError

  from pydantic_core import PydanticCustomError

  Raise inside custom validators to emit structured validation errors with a custom error type and message template
• PydanticSerializationUnexpectedValue

  from pydantic_core import PydanticSerializationUnexpectedValue

  Raise inside custom field_serializer functions when the runtime value type does not match the declared type
• CoreSchema (type alias)

  from pydantic_core import CoreSchema

  TypedDict type alias for the CoreSchema dict structure; useful for type annotations in __get_pydantic_core_schema__ signatures

Quickstart

Directly construct and use a SchemaValidator with core_schema helpers. Most users should use the higher-level pydantic.BaseModel instead; this API is for library authors or performance-critical custom validation pipelines.

from pydantic_core import SchemaValidator, ValidationError, core_schema

# Build a schema using the core_schema helpers
schema = core_schema.typed_dict_schema(
    {
        'name': core_schema.typed_dict_field(core_schema.str_schema()),
        'age': core_schema.typed_dict_field(
            core_schema.int_schema(ge=18)
        ),
        'is_developer': core_schema.typed_dict_field(
            core_schema.with_default_schema(
                core_schema.bool_schema(), default=True
            ),
            required=False,
        ),
    }
)

v = SchemaValidator(schema)

# Validate a Python dict
result = v.validate_python({'name': 'Alice', 'age': 30})
print(result)  # {'name': 'Alice', 'age': 30, 'is_developer': True}

# Validate JSON bytes directly (faster than json.loads + validate_python)
result_json = v.validate_json('{"name": "Bob", "age": 25}')
print(result_json)

# Catch validation errors
try:
    v.validate_python({'name': 'Eve', 'age': 15})
except ValidationError as e:
    print(e)
    # 1 validation error for typed-dict
    # age
    #   Input should be greater than or equal to 18 [type=greater_than_equal, ...]