Install & Compatibility
Where this runs
tested against v2.48.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.100s · 27.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.2s · import 0.087s · 27MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SchemaValidator
✓ from pydantic_core import SchemaValidator
✗ from pydantic_core._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
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, ...]
Debug
Known issues
breakingpydantic-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.fixAlways install and upgrade pydantic, not pydantic-core directly. Let pydantic's dependency constraint select the correct pydantic-core version automatically.
affects: all
breakingThe 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.fixAlways 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.
affects: all
breakingOn 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.fixAlways 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.
affects: all
breakingDeploying 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.fixPass 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'). affects: all
breakingPydantic V1 is not compatible with Python 3.14 or greater. pydantic-core (V2) is required for Python 3.14+ support.fixMigrate to pydantic V2 (which uses pydantic-core). The compatibility shim `from pydantic import v1 as pydantic_v1` is available for incremental migration.
affects: <2.0 (pydantic V1)
gotchavalidate_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.fixCall v.validate_json(json_bytes_or_str) directly instead of v.validate_python(json.loads(json_bytes_or_str)).
affects: all
gotchaImporting 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.fixImport 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/.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'
This error occurs when the Python interpreter cannot find the compiled Rust extension module (_pydantic_core) that underpins pydantic-core. This is often due to a mismatch between the environment where the package was built (e.g., your local machine) and the environment where it's being run (e.g., a Docker container or AWS Lambda function) in terms of operating system, CPU architecture, or Python version.
fixEnsure `pydantic-core` is installed with the correct platform and Python version binaries for your target environment. For deployment in environments like AWS Lambda or Docker, use `pip install --platform <platform> --python-version <python_version> --only-binary=:all: <package_name>` or build your dependencies inside a compatible Linux Docker container. For example, for AWS Lambda x86_64 and Python 3.10: `pip install pydantic-core --platform manylinux2014_x86_64 --python-version 3.10 -t . --only-binary=:all:`.
pydantic_core._pydantic_core.ValidationError: 1 validation error for ...
This exception is raised directly by the underlying Rust engine of `pydantic-core` when input data does not conform to the defined schema during validation. While `pydantic` typically wraps this error, seeing the `_pydantic_core` prefix indicates its origin deep within the Rust validation logic.
fixCatch the `pydantic.ValidationError` (which is aliased to `pydantic_core.ValidationError`) and inspect its `errors()` method to get detailed information about the validation failures, including the location (`loc`), error message (`msg`), input value (`input`), and error type. Adjust the input data or modify your Pydantic model's schema to resolve the validation issues based on these details.
AttributeError: module 'pydantic_core' has no attribute '...' (e.g., 'TuplePositionalSchema' or 'tuple_schema')
This error typically occurs when attempting to directly access attributes, classes, or schema builders from the `pydantic_core` module that are not part of its public API, have been renamed, or were removed in a specific version. `pydantic-core` is primarily an internal engine for `pydantic`, and direct interaction is discouraged for most end-users.
fixAvoid direct imports and usage of `pydantic_core` internals unless you are a library author implementing custom types via `__get_pydantic_core_schema__`. For general data validation and serialization, use the higher-level `pydantic` API (e.g., `pydantic.BaseModel`, `pydantic.TypeAdapter`). If you are a library author, consult the `pydantic-core.core_schema` documentation for the correct, current schema builder functions and types for your specific `pydantic-core` version.
Upgrade
Version history
2.48.0latest on PyPI · released Aug 6, 2026
Audit
Dependencies
typing-extensionsrequiredRequired for backported type constructs used in core_schema type hints; must be >=4.6.0