{"id":"6af190c2d94bb40a","repo":"pydantic/pydantic","slug":"the-installed-pydantic-core-version-pydantic-c","errorCode":null,"errorMessage":"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.","messagePattern":"The installed pydantic-core version \\((.+?)\\) is incompatible with the current pydantic version, which requires (.+?)\\. If you encounter this error, make sure that you haven't upgraded pydantic-core manually\\.","errorType":"exception","errorClass":"SystemError","httpStatus":null,"severity":"critical","filePath":"pydantic/version.py","lineNumber":94,"sourceCode":"\ndef check_pydantic_core_version() -> bool:\n    \"\"\"Check that the installed `pydantic-core` dependency is compatible.\"\"\"\n    return __pydantic_core_version__ == _COMPATIBLE_PYDANTIC_CORE_VERSION\n\n\ndef _ensure_pydantic_core_version() -> None:  # pragma: no cover\n    if not check_pydantic_core_version():\n        raise_error = True\n        # Do not raise the error if pydantic is installed in editable mode (i.e. in development):\n        if sys.version_info >= (3, 13):  # origin property added in 3.13\n            from importlib.metadata import distribution\n\n            dist = distribution('pydantic')\n            if getattr(getattr(dist.origin, 'dir_info', None), 'editable', False):\n                raise_error = False\n\n        if raise_error:\n            raise SystemError(\n                f'The installed pydantic-core version ({__pydantic_core_version__}) is incompatible '\n                f'with the current pydantic version, which requires {_COMPATIBLE_PYDANTIC_CORE_VERSION}. '\n                \"If you encounter this error, make sure that you haven't upgraded pydantic-core manually.\"\n            )\n\n\ndef parse_mypy_version(version: str) -> tuple[int, int, int]:\n    \"\"\"Parse `mypy` string version to a 3-tuple of ints.\n\n    It parses normal version like `1.11.0` and extra info followed by a `+` sign\n    like `1.11.0+dev.d6d9d8cd4f27c52edac1f537e236ec48a01e54cb.dirty`.\n\n    Args:\n        version: The mypy version string.\n\n    Returns:\n        A triple of ints, e.g. `(1, 11, 0)`.\n    \"\"\"","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/pydantic/pydantic/blob/2e5f0e2b4218de31709f1cf9c5bc61ea97a68835/pydantic/version.py#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (mismatched environment)\n$ python -c \"import pydantic\"\nSystemError: The installed pydantic-core version (2.45.1) is incompatible ...\n\n// after\n$ pip install --force-reinstall pydantic\n$ python -c \"import pydantic; print(pydantic.VERSION)\"","handlingStrategy":"validation","validationCode":"from pydantic.version import check_pydantic_core_version\n\ndef assert_compatible_core() -> None:\n    if not check_pydantic_core_version():\n        from pydantic.version import _COMPATIBLE_PYDANTIC_CORE_VERSION\n        raise RuntimeError(\n            f'pydantic-core mismatch; install pydantic-core=={_COMPATIBLE_PYDANTIC_CORE_VERSION}'\n        )\n\n# call assert_compatible_core() in CI before importing the app","typeGuard":"from pydantic.version import check_pydantic_core_version\n\ndef environment_is_pydantic_compatible() -> bool:\n    return check_pydantic_core_version()","tryCatchPattern":"try:\n    import pydantic\nexcept SystemError as e:\n    if 'incompatible' in str(e):\n        # halt deploy; rebuild venv with pinned pydantic + pydantic-core\n        raise SystemExit('FATAL: pydantic/pydantic-core version mismatch')\n    raise","preventionTips":["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."],"tags":["version-mismatch","pydantic-core","import-time","environment","dependency-management"],"analyzedSha":"2e5f0e2b4218de31709f1cf9c5bc61ea97a68835","analyzedAt":"2026-08-04T19:54:21.281Z","schemaVersion":2}