pola-rs/polars · critical

could not find Polars' Rust module

Error message

could not find Polars' Rust module

What it means

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.

Source

Thrown at py-polars/src/polars/_plr.py:98

                if sys.modules[__name__].__version__ != PKG_VERSION:
                    import warnings

                    version_warnings += [sys.modules[__name__].__version__]
                    warnings.warn(
                        f"Skipping Polars' Rust module version '{sys.modules[__name__].__version__}' did not match version of Python package '{PKG_VERSION}'.",
                        ImportWarning,
                        stacklevel=2,
                    )
                    continue

                break
            except ImportError:
                pass
        else:
            msg = "could not find Polars' Rust module"
            if len(version_warnings) > 0:
                msg += f". Skipped versions {version_warnings} which don't match Python package version"
            raise ImportError(msg)


# The version at the top here should match the version specified by the PLR.
assert sys.modules[__name__].__version__ == PKG_VERSION

View on GitHub (pinned to df599052da)

Solutions

1. 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`
2. Confirm a single coherent source and version set: `pip list | grep -i polars` — remove conda-provided duplicates
3. If the message lists skipped versions, those specific runtime wheels are stale and must be removed/reinstalled
4. Last resort: recreate the virtualenv and reinstall from scratch

Example fix

# before
import polars as pl  # ImportError: could not find Polars' Rust module. Skipped versions ['1.40.0'] ...

# after
# pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32
# pip install --upgrade polars
import polars as pl

import importlib.util, importlib.metadata as md

# preflight: at least one runtime package must be importable and version-matched
ver = md.version("polars")
ok = False
for pkg, mod in (("polars-runtime-compat", "_polars_runtime_compat"),
                 ("polars-runtime-64", "_polars_runtime_64"),
                 ("polars-runtime-32", "_polars_runtime_32")):
    if importlib.util.find_spec(mod) is not None:
        try:
            ok = ok or md.version(pkg) == ver
        except md.PackageNotFoundError:
            pass
if not ok:
    raise RuntimeError("no matching polars Rust runtime installed — clean reinstall needed")

try:
    import polars as pl
except ImportError as e:
    if "could not find Polars' Rust module" not in str(e):
        raise
    # install cannot be fixed in-process; fail loudly with the repair command
    raise SystemExit("broken polars install — run: pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32 && pip install --upgrade polars")

When it happens

Trigger: `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).

Common situations: 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.

Related errors

• Polars Rust module for '{_force}' ({sys.modules[__name__].__
• unknown feature flag: {f!r}
• Invalid value for `POLARS_FORCE_PKG` variable: '{_force}'
• Invalid value for `POLARS_PREFER_PKG` variable: '{_prefer}'
• could not allocate memory for CPUID check

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/725e9274975a46b6. Report an issue: GitHub.