{"record":{"id":"725e9274975a46b6","repo":"pola-rs/polars","slug":"could-not-find-polars-rust-module","errorCode":null,"errorMessage":"could not find Polars' Rust module","messagePattern":"could not find Polars' Rust module","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"py-polars/src/polars/_plr.py","lineNumber":98,"sourceCode":"                if sys.modules[__name__].__version__ != PKG_VERSION:\n                    import warnings\n\n                    version_warnings += [sys.modules[__name__].__version__]\n                    warnings.warn(\n                        f\"Skipping Polars' Rust module version '{sys.modules[__name__].__version__}' did not match version of Python package '{PKG_VERSION}'.\",\n                        ImportWarning,\n                        stacklevel=2,\n                    )\n                    continue\n\n                break\n            except ImportError:\n                pass\n        else:\n            msg = \"could not find Polars' Rust module\"\n            if len(version_warnings) > 0:\n                msg += f\". Skipped versions {version_warnings} which don't match Python package version\"\n            raise ImportError(msg)\n\n\n# The version at the top here should match the version specified by the PLR.\nassert sys.modules[__name__].__version__ == PKG_VERSION\n","sourceCodeStart":80,"sourceCodeEnd":103,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_plr.py#L80-L103","documentation":"At import, polars tries each Rust runtime package in preference order (compat, 64, 32; POLARS_PREFER_PKG moves one to the front). Runtimes that raise ImportError are skipped, and runtimes whose __version__ doesn't match the Python package only emit an ImportWarning and are skipped too. If the loop exhausts with no successful load, this ImportError is raised — listing any skipped versions — meaning the Rust extension modules are missing or all mismatched: a broken or partially-upgraded install.","triggerScenarios":"`import polars` when no `_polars_runtime_*` package is importable (deleted site-packages files, broken venv after being moved/copied, interrupted wheel install), or when every installed runtime belongs to a different polars version than the Python wheel (stale polars-runtime-* after an upgrade).","commonSituations":"Interrupted `pip install -U polars`; venvs copied across machines so binary wheels broke; mixing pip and conda-forge polars; Docker layer caching an old runtime wheel under a new polars layer; downgrades that leave mismatched runtime packages behind.","solutions":["Clean reinstall: `pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32` (repeat until `pip list | grep -i polars` is empty), then `pip install --upgrade --force-reinstall polars`","Confirm a single coherent source and version set: `pip list | grep -i polars` — remove conda-provided duplicates","If the message lists skipped versions, those specific runtime wheels are stale and must be removed/reinstalled","Last resort: recreate the virtualenv and reinstall from scratch"],"exampleFix":"# before\nimport polars as pl  # ImportError: could not find Polars' Rust module. Skipped versions ['1.40.0'] ...\n\n# after\n# pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32\n# pip install --upgrade polars\nimport polars as pl","handlingStrategy":"retry","validationCode":"import importlib.util, importlib.metadata as md\n\n# preflight: at least one runtime package must be importable and version-matched\nver = md.version(\"polars\")\nok = False\nfor pkg, mod in ((\"polars-runtime-compat\", \"_polars_runtime_compat\"),\n                 (\"polars-runtime-64\", \"_polars_runtime_64\"),\n                 (\"polars-runtime-32\", \"_polars_runtime_32\")):\n    if importlib.util.find_spec(mod) is not None:\n        try:\n            ok = ok or md.version(pkg) == ver\n        except md.PackageNotFoundError:\n            pass\nif not ok:\n    raise RuntimeError(\"no matching polars Rust runtime installed — clean reinstall needed\")","typeGuard":null,"tryCatchPattern":"try:\n    import polars as pl\nexcept ImportError as e:\n    if \"could not find Polars' Rust module\" not in str(e):\n        raise\n    # install cannot be fixed in-process; fail loudly with the repair command\n    raise SystemExit(\"broken polars install — run: pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32 && pip install --upgrade polars\")","preventionTips":["Never interrupt `pip install -U polars`; if it fails, uninstall the whole family before retrying","Recreate (don't copy/move) virtualenvs that contain polars binary wheels","Use one package source (pip OR conda) for all polars components","Add a startup preflight that compares polars and polars-runtime-* versions via importlib.metadata"],"tags":["import-time","broken-install","version-mismatch","packaging","rust-runtime"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}