{"id":268,"library":"pydantic-core","title":"pydantic-core","description":"pydantic-core is the Rust-powered engine that underpins all validation and serialization in Pydantic V2+. Written in Rust via PyO3, it exposes SchemaValidator, SchemaSerializer, ValidationError, and the core_schema builder API to Python. End-users should interact with it only through the higher-level `pydantic` package; direct use is intended for library authors implementing custom types via __get_pydantic_core_schema__. The library releases in lockstep with pydantic — each pydantic-core version is pinned to exactly one pydantic version and does not follow SemVer independently. Current version is 2.44.0, released frequently (multiple times per month) alongside pydantic.","status":"active","version":"2.44.0","language":"python","source_language":"en","source_url":"https://github.com/pydantic/pydantic-core","tags":["validation","serialization","rust","pydantic","data-modeling","type-checking","json"],"install":[{"cmd":"pip install pydantic-core","lang":"bash","label":"Install via pip (binary wheel, no Rust required)"},{"cmd":"pip install pydantic","lang":"bash","label":"Preferred: install via pydantic (pulls correct pydantic-core version automatically)"}],"dependencies":[{"reason":"Required for backported type constructs used in core_schema type hints; must be >=4.6.0","package":"typing-extensions","optional":false}],"imports":[{"note":"Always import from the top-level pydantic_core package, not from the private _pydantic_core Rust extension module directly","wrong":"from pydantic_core._pydantic_core import SchemaValidator","symbol":"SchemaValidator","correct":"from pydantic_core import SchemaValidator"},{"note":"Python wrapper around the Rust serialization logic; use for custom standalone serializers","symbol":"SchemaSerializer","correct":"from pydantic_core import SchemaSerializer"},{"note":"Raised by SchemaValidator on invalid input; also re-exported from pydantic","symbol":"ValidationError","correct":"from pydantic_core import ValidationError"},{"note":"Module containing all schema builder functions (str_schema, int_schema, typed_dict_schema, etc.) used to construct CoreSchema dicts","symbol":"core_schema","correct":"from pydantic_core import core_schema"},{"note":"Raise inside custom validators to emit structured validation errors with a custom error type and message template","symbol":"PydanticCustomError","correct":"from pydantic_core import PydanticCustomError"},{"note":"Raise inside custom field_serializer functions when the runtime value type does not match the declared type","symbol":"PydanticSerializationUnexpectedValue","correct":"from pydantic_core import PydanticSerializationUnexpectedValue"},{"note":"TypedDict type alias for the CoreSchema dict structure; useful for type annotations in __get_pydantic_core_schema__ signatures","symbol":"CoreSchema (type alias)","correct":"from pydantic_core import CoreSchema"}],"quickstart":{"code":"from pydantic_core import SchemaValidator, ValidationError, core_schema\n\n# Build a schema using the core_schema helpers\nschema = core_schema.typed_dict_schema(\n    {\n        'name': core_schema.typed_dict_field(core_schema.str_schema()),\n        'age': core_schema.typed_dict_field(\n            core_schema.int_schema(ge=18)\n        ),\n        'is_developer': core_schema.typed_dict_field(\n            core_schema.with_default_schema(\n                core_schema.bool_schema(), default=True\n            ),\n            required=False,\n        ),\n    }\n)\n\nv = SchemaValidator(schema)\n\n# Validate a Python dict\nresult = v.validate_python({'name': 'Alice', 'age': 30})\nprint(result)  # {'name': 'Alice', 'age': 30, 'is_developer': True}\n\n# Validate JSON bytes directly (faster than json.loads + validate_python)\nresult_json = v.validate_json('{\"name\": \"Bob\", \"age\": 25}')\nprint(result_json)\n\n# Catch validation errors\ntry:\n    v.validate_python({'name': 'Eve', 'age': 15})\nexcept ValidationError as e:\n    print(e)\n    # 1 validation error for typed-dict\n    # age\n    #   Input should be greater than or equal to 18 [type=greater_than_equal, ...]\n","lang":"python","description":"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."},"warnings":[{"fix":"Always install and upgrade pydantic, not pydantic-core directly. Let pydantic's dependency constraint select the correct pydantic-core version automatically.","message":"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.","severity":"breaking","affected_versions":"all"},{"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.","message":"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.","severity":"breaking","affected_versions":"all"},{"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.","message":"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.","severity":"breaking","affected_versions":"all"},{"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').","message":"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.","severity":"breaking","affected_versions":"all"},{"fix":"Migrate to pydantic V2 (which uses pydantic-core). The compatibility shim `from pydantic import v1 as pydantic_v1` is available for incremental migration.","message":"Pydantic V1 is not compatible with Python 3.14 or greater. pydantic-core (V2) is required for Python 3.14+ support.","severity":"breaking","affected_versions":"<2.0 (pydantic V1)"},{"fix":"Call v.validate_json(json_bytes_or_str) directly instead of v.validate_python(json.loads(json_bytes_or_str)).","message":"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.","severity":"gotcha","affected_versions":"all"},{"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/.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T12:38:52.714Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure `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:`.","cause":"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.","error":"ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'"},{"fix":"Catch 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.","cause":"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.","error":"pydantic_core._pydantic_core.ValidationError: 1 validation error for ..."},{"fix":"Avoid 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.","cause":"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.","error":"AttributeError: module 'pydantic_core' has no attribute '...' (e.g., 'TuplePositionalSchema' or 'tuple_schema')"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":5.4,"disk_size":"27.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":5.4,"disk_size":"23.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":5.3,"disk_size":"27M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":5.4,"disk_size":"24M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":6.5,"disk_size":"30.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":6.5,"disk_size":"25.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.22,"mem_mb":6.5,"disk_size":"30M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.23,"mem_mb":6.5,"disk_size":"25M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":9.4,"disk_size":"22.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":9.4,"disk_size":"17.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":9.4,"disk_size":"22M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.48,"mem_mb":9.4,"disk_size":"17M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":3.1,"disk_size":"21.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":3.1,"disk_size":"17.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.9,"disk_size":"21M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.9,"disk_size":"17M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":5.3,"disk_size":"27.2M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":5.3,"disk_size":"23.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":5.3,"disk_size":"27M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":5.3,"disk_size":"23M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}