pola-rs/polars · critical · ImportError

could not find Polars' Rust module. Skipped versions

Error message

could not find Polars' Rust module. Skipped versions {version_warnings} which don't match Python package version

What it means

Polars tried every Rust extension package in its preference order and none could be imported. Each candidate whose version did not match the Python package version was recorded in version_warnings and skipped; if no import succeeded, ImportError is raised, appending the skipped versions when any exist.

Solutions

Reinstall the whole Polars set at one version: `pip install --force-reinstall -U polars` (plus any -lts-cpu/-u64-idx variant you use)
Ensure exactly the compatible wheel variant for your platform is installed and version-matched
Check for shadowing: run `pip show polars` and confirm the import path points at your intended site-packages
If a custom variant is required, set POLARS_FORCE_PKG to a valid name and match its version to polars

Example fix

// before
import polars as pl  # ImportError: could not find Polars' Rust module. Skipped versions [...] 
// after
$ pip install --force-reinstall -U polars polars-lts-cpu
import polars as pl  # works

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.metadata as md
vers = {p: md.version(p) for p in md.packages_distributions().get('polars', [])}
assert len(set(vers.values())) == 1, f'mismatched polars installs: {vers}'

Try / catch

try:
    import polars as pl
except ImportError as e:
    raise RuntimeError('Reinstall polars: pip install --force-reinstall -U polars') from e

Prevention

Install polars and all variants together in one pip/uv command
Never mix polars versions within one environment (check with pip list)
Rebuild images from lockfiles after upgrades; avoid partial installs
Test `import polars` as a smoke test in CI before heavier jobs

When it happens

Trigger: Importing polars when: no Rust wheel matching the Python package version is installed (e.g. only polars-lts-cpu present at a different version); all candidates were skipped due to version mismatch; or the compiled module is unusable on the platform.

Common situations: Broken upgrades where Python polars is new but companion wheels are old; unsupported/odd platforms where only mismatched wheels resolved; corrupted site-packages after interrupted installs.

Related errors

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

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