pydantic/pydantic · critical · SystemError

The installed pydantic-core version ({__pydantic_core_versio

Error message

The installed pydantic-core version ({__pydantic_core_version__}) is incompatible with the current pydantic version, which requires {_COMPATIBLE_PYDANTIC_CORE_VERSION}. If you encounter this error, make sure that you haven't upgraded pydantic-core manually.

What it means

Raised as a SystemError at import time by pydantic.version._ensure_pydantic_core_version (pydantic/version.py:94), invoked once from pydantic/__init__.py:8. pydantic pins an exact required pydantic-core version (_COMPATIBLE_PYDANTIC_CORE_VERSION, e.g. '2.47.0') that must match the installed pydantic_core.__version__ exactly; any mismatch aborts import. The check is skipped only when pydantic itself is installed in editable/development mode under Python 3.13+. This protects the ABI-coupled Rust core from running against an incompatible Python wrapper.

Source

Thrown at pydantic/version.py:94

def check_pydantic_core_version() -> bool:
    """Check that the installed `pydantic-core` dependency is compatible."""
    return __pydantic_core_version__ == _COMPATIBLE_PYDANTIC_CORE_VERSION


def _ensure_pydantic_core_version() -> None:  # pragma: no cover
    if not check_pydantic_core_version():
        raise_error = True
        # Do not raise the error if pydantic is installed in editable mode (i.e. in development):
        if sys.version_info >= (3, 13):  # origin property added in 3.13
            from importlib.metadata import distribution

            dist = distribution('pydantic')
            if getattr(getattr(dist.origin, 'dir_info', None), 'editable', False):
                raise_error = False

        if raise_error:
            raise SystemError(
                f'The installed pydantic-core version ({__pydantic_core_version__}) is incompatible '
                f'with the current pydantic version, which requires {_COMPATIBLE_PYDANTIC_CORE_VERSION}. '
                "If you encounter this error, make sure that you haven't upgraded pydantic-core manually."
            )


def parse_mypy_version(version: str) -> tuple[int, int, int]:
    """Parse `mypy` string version to a 3-tuple of ints.

    It parses normal version like `1.11.0` and extra info followed by a `+` sign
    like `1.11.0+dev.d6d9d8cd4f27c52edac1f537e236ec48a01e54cb.dirty`.

    Args:
        version: The mypy version string.

    Returns:
        A triple of ints, e.g. `(1, 11, 0)`.
    """

View on GitHub (pinned to 2e5f0e2b42)

Solutions

Reinstall pydantic as a unit so pip resolves the matching pydantic-core: pip install --force-reinstall pydantic.
Pin both packages to a known-good pair in requirements.txt (e.g. pydantic==2.14.0a1 and pydantic-core==2.47.0).
Clear pip/Docker layer caches that may hold a stale pydantic-core wheel and rebuild the environment.
If developing pydantic itself, install it in editable mode under Python 3.13+ to bypass the check, or align the core version manually.

Example fix

// before (mismatched environment)
$ python -c "import pydantic"
SystemError: The installed pydantic-core version (2.45.1) is incompatible ...

// after
$ pip install --force-reinstall pydantic
$ python -c "import pydantic; print(pydantic.VERSION)"

Defensive patterns

Strategy: validation

Validate before calling

from pydantic.version import check_pydantic_core_version

def assert_compatible_core() -> None:
    if not check_pydantic_core_version():
        from pydantic.version import _COMPATIBLE_PYDANTIC_CORE_VERSION
        raise RuntimeError(
            f'pydantic-core mismatch; install pydantic-core=={_COMPATIBLE_PYDANTIC_CORE_VERSION}'
        )

# call assert_compatible_core() in CI before importing the app

Type guard

from pydantic.version import check_pydantic_core_version

def environment_is_pydantic_compatible() -> bool:
    return check_pydantic_core_version()

Try / catch

try:
    import pydantic
except SystemError as e:
    if 'incompatible' in str(e):
        # halt deploy; rebuild venv with pinned pydantic + pydantic-core
        raise SystemExit('FATAL: pydantic/pydantic-core version mismatch')
    raise

Prevention

Pin both pydantic and pydantic-core explicitly in requirements.txt / poetry.lock / uv.lock.
Install pydantic as a unit (pip install pydantic) so pip resolves the matching core.
Add a startup probe that calls check_pydantic_core_version() in CI and containers.
Rebuild Docker layers and clear pip caches when upgrading pydantic to avoid stale core wheels.

When it happens

Trigger: Importing pydantic after pydantic-core was upgraded or downgraded independently (pip install --upgrade pydantic-core, a transitive dependency resolution change, mixing conda/pip installs, a stale wheel in a Docker layer cache). Any mismatch — even a patch-level one — triggers it because the constraint is an exact equality.

Common situations: CI image with cached layers pinning an older pydantic-core while pydantic was bumped; pip resolving pydantic and pydantic-core from different releases after a partial upgrade; downgrading pydantic without downgrading pydantic-core; editable dev installs that bypass the check on 3.13 but fail in production on 3.12.

Related errors

module 'pydantic_core' has no attribute '{attr_name}'

AI-assisted analysis of pydantic/pydantic@2e5f0e2b42 (2026-08-04). Data as JSON: /data/errors/6af190c2d94bb40a.json. Report an issue: GitHub.