pola-rs/polars · error · ImportError

Polars Rust module for '{_force}' ({version}) did not match

Error message

Polars Rust module for '{_force}' ({version}) did not match version of Python package '{PKG_VERSION}'

What it means

Version-consistency check when POLARS_FORCE_PKG pins a specific Polars binary variant: the forced Rust module (compat/64/32) loaded successfully but its __version__ differs from the Python package's PKG_VERSION, meaning mismatched polars and polars-*-variants installs. Reinstalling matching versions fixes it.

Source

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

if hasattr(builtins, "__POLARS_PLR"):
    sys.modules[__name__] = builtins.__POLARS_PLR
else:
    # Each of the Polars variants registers a `_polars...` package that we can import
    # the PLR from.

    _force = os.environ.get("POLARS_FORCE_PKG")
    _prefer = os.environ.get("POLARS_PREFER_PKG")

    pkgs = {"compat": rt_compat, "64": rt_64, "32": rt_32}
    default_prefer = [rt_compat, rt_64, rt_32]

    if _force is not None:
        try:
            pkgs[_force]()

            if sys.modules[__name__].__version__ != PKG_VERSION:
                msg = f"Polars Rust module for '{_force}' ({sys.modules[__name__].__version__}) did not match version of Python package '{PKG_VERSION}'"
                raise ImportError(msg)
        except KeyError:
            msg = f"Invalid value for `POLARS_FORCE_PKG` variable: '{_force}'"
            raise ValueError(msg) from None
    else:
        preference = default_prefer
        if _prefer is not None:
            try:
                preference.insert(0, pkgs[_prefer])
            except KeyError:
                msg = f"Invalid value for `POLARS_PREFER_PKG` variable: '{_prefer}'"
                raise ValueError(msg) from None

        version_warnings = []
        for pkg in preference:
            try:
                pkg()

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

View on GitHub (pinned to 5d8ebabf11)

Solutions

1. Reinstall polars so the Rust module matches the Python package version: pip install -U --force-reinstall polars. Avoid mixing polars and polars-runtime-32 builds.

Example fix

pip install -U --force-reinstall polars

When it happens

Trigger: The loaded Polars Rust module version differs from the Python package version.

Common situations: See trigger scenarios.

AI-assisted analysis of pola-rs/polars@5d8ebabf11 (2026-08-19). Data as JSON: /api/errors/d89d947706168166. Report an issue: GitHub.