Polars Rust module for '{_force}' ({sys.modules[name].__

Error message

Polars Rust module for '{_force}' ({sys.modules[__name__].__version__}) did not match version of Python package '{PKG_VERSION}'

What it means

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.

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 df599052da)

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

Example fix

# before
# env: POLARS_FORCE_PKG=64, site-packages has polars 1.43.2 + stale polars-runtime-64 1.40.0
import polars as pl  # ImportError: Polars Rust module for '64' (1.40.0) did not match ...

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

Defensive patterns

Strategy: validation

Validate before calling

import importlib.metadata as md

ver = md.version("polars")
for rt in ("polars-runtime-compat", "polars-runtime-64", "polars-runtime-32"):
    try:
        if md.version(rt) != ver:
            raise RuntimeError(f"{rt} {md.version(rt)} != polars {ver}: remove POLARS_FORCE_PKG and reinstall")
    except md.PackageNotFoundError:
        pass

Try / catch

try:
    import polars as pl
except ImportError as e:
    if "did not match version" in str(e):
        raise SystemExit("forced runtime version mismatch — unset POLARS_FORCE_PKG and reinstall all polars packages")
    raise

Prevention

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

When it happens

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

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

Related errors

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