pola-rs/polars · error · ImportError

Polars Rust module for

Error message

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

What it means

When POLARS_FORCE_PKG selects a specific Rust extension package, Polars verifies that the loaded Rust module's version equals the Python package version (PKG_VERSION). A mismatch means the wheel set is inconsistent (Python and Rust halves out of sync), so an ImportError is raised rather than risking ABI/behavior breakage.

Solutions

Reinstall the matched set in one command: `pip install -U polars polars-lts-cpu` (or the forced package name)
Check `pip list | grep polars` and align every polars* package to the same version
Remove the POLARS_FORCE_PKG env var if the specific wheel variant is not actually required
Clear the environment/uv/pip cache and reinstall if versions appear equal but the error persists

Example fix

// before
$ POLARS_FORCE_PKG=polars-lts-cpu python -c 'import polars'  # ImportError: version mismatch
// after
$ pip install -U polars polars-lts-cpu
$ python -c 'import polars'

Defensive patterns

Strategy: validation

Validate before calling

import os, importlib.metadata as md
force = os.environ.get('POLARS_FORCE_PKG')
if force:
    v_py = md.version('polars')
    v_ext = md.version(force) if force != 'polars' else v_py
    assert v_py == v_ext, f'{force} {v_ext} != polars {v_py}'

Try / catch

try:
    import polars as pl
except ImportError:
    os.environ.pop('POLARS_FORCE_PKG', None)
    import polars as pl

Prevention

Always upgrade polars and its companion wheels in a single command
Avoid exporting POLARS_FORCE_PKG globally; scope it to the shell/job that needs it
Run `pip list | grep polars` in CI to verify version alignment
Keep the force variable in infrastructure-as-code, not ad-hoc exports

When it happens

Trigger: Setting env var POLARS_FORCE_PKG=<name> (e.g. polars-lts-cpu, polars-u64-idx) where the selected Rust package's compiled version differs from the installed polars Python package version; mixing releases during upgrade/downgrade; stale cached wheels after `pip install -U`.

Common situations: Upgrading polars without upgrading its companion wheel (or vice versa); partial installs in monorepo lockfiles; pinning a force-PKG variable in CI that resolves to a lagging package version.

Related errors

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

Appendix: 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 fe841f959e)