{"record":{"id":"3b3e8c391ced3be8","repo":"pola-rs/polars","slug":"polars-rust-module-for-force-sys-modules","errorCode":null,"errorMessage":"Polars Rust module for '{_force}' ({sys.modules[__name__].__version__}) did not match version of Python package '{PKG_VERSION}'","messagePattern":"Polars Rust module for '(.+?)' \\((.+?)\\) did not match version of Python package '(.+?)'","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"py-polars/src/polars/_plr.py","lineNumber":62,"sourceCode":"if hasattr(builtins, \"__POLARS_PLR\"):\n    sys.modules[__name__] = builtins.__POLARS_PLR\nelse:\n    # Each of the Polars variants registers a `_polars...` package that we can import\n    # the PLR from.\n\n    _force = os.environ.get(\"POLARS_FORCE_PKG\")\n    _prefer = os.environ.get(\"POLARS_PREFER_PKG\")\n\n    pkgs = {\"compat\": rt_compat, \"64\": rt_64, \"32\": rt_32}\n    default_prefer = [rt_compat, rt_64, rt_32]\n\n    if _force is not None:\n        try:\n            pkgs[_force]()\n\n            if sys.modules[__name__].__version__ != PKG_VERSION:\n                msg = f\"Polars Rust module for '{_force}' ({sys.modules[__name__].__version__}) did not match version of Python package '{PKG_VERSION}'\"\n                raise ImportError(msg)\n        except KeyError:\n            msg = f\"Invalid value for `POLARS_FORCE_PKG` variable: '{_force}'\"\n            raise ValueError(msg) from None\n    else:\n        preference = default_prefer\n        if _prefer is not None:\n            try:\n                preference.insert(0, pkgs[_prefer])\n            except KeyError:\n                msg = f\"Invalid value for `POLARS_PREFER_PKG` variable: '{_prefer}'\"\n                raise ValueError(msg) from None\n\n        version_warnings = []\n        for pkg in preference:\n            try:\n                pkg()\n\n                if sys.modules[__name__].__version__ != PKG_VERSION:","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_plr.py#L44-L80","documentation":"POLARS_FORCE_PKG forces polars to load exactly one Rust runtime package ('compat', '64', or '32' mapping to the `_polars_runtime_*` distributions). After forcing, polars asserts the loaded runtime's __version__ equals the Python package version (PKG_VERSION in polars/_plr.py). This ImportError means the forced runtime wheel belongs to a different polars release than the Python `polars` wheel — a split/mixed install.","triggerScenarios":"Import-time, when POLARS_FORCE_PKG=compat|64|32 is set and the selected runtime package is stale or newer than the polars wheel — e.g. after `pip install -U polars` left an old `polars-runtime-*`, or when mixing pip and conda installs.","commonSituations":"Environments that set POLARS_FORCE_PKG to pin a CPU-compatible variant and later upgraded polars; CI caches reusing old runtime wheels; half-completed upgrades where the new runtime wheel failed to install.","solutions":["Unset POLARS_FORCE_PKG and import again — polars then auto-selects; if versions still mismatch you will get the clearer 'could not find Polars' Rust module' error","Clean reinstall the whole family: `pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32 && pip install polars`","Ensure a single source provides the packages (pip OR conda, not both): `pip list | grep -i polars` must show one coherent version set"],"exampleFix":"# before\n# env: POLARS_FORCE_PKG=64, site-packages has polars 1.43.2 + stale polars-runtime-64 1.40.0\nimport polars as pl  # ImportError: Polars Rust module for '64' (1.40.0) did not match ...\n\n# after\n# unset POLARS_FORCE_PKG\n# pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32\n# pip install polars\nimport polars as pl","handlingStrategy":"validation","validationCode":"import importlib.metadata as md\n\nver = md.version(\"polars\")\nfor rt in (\"polars-runtime-compat\", \"polars-runtime-64\", \"polars-runtime-32\"):\n    try:\n        if md.version(rt) != ver:\n            raise RuntimeError(f\"{rt} {md.version(rt)} != polars {ver}: remove POLARS_FORCE_PKG and reinstall\")\n    except md.PackageNotFoundError:\n        pass","typeGuard":null,"tryCatchPattern":"try:\n    import polars as pl\nexcept ImportError as e:\n    if \"did not match version\" in str(e):\n        raise SystemExit(\"forced runtime version mismatch — unset POLARS_FORCE_PKG and reinstall all polars packages\")\n    raise","preventionTips":["Only set POLARS_FORCE_PKG when you also pin/verify the whole polars package family to one version","After any polars upgrade, re-check `pip list | grep -i polars` before running with FORCE set","Prefer relying on default auto-selection unless you specifically need to test one runtime variant"],"tags":["version-mismatch","environment-variables","import-time","packaging","rust-runtime"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}