pola-rs/polars · critical

unknown feature flag: {f!r}

Error message

unknown feature flag: {f!r}

What it means

check_cpu_flags splits the BUILD_FEATURE_FLAGS string baked into the installed `_polars_runtime_*` wheel at build time and validates each flag against a fixed table of known CPUID features (sse3..lzcnt, with 'ctr-static' ignored). This RuntimeError means the wheel declares a feature name the Python-side table does not know — i.e. the Python `polars` package and the Rust `_polars_runtime_*` package come from different releases (the runtime wheel is newer than the Python code that must interpret its flags).

Source

Thrown at py-polars/src/polars/_cpu_check.py:263

    expected_cpu_flags = [
        f.lstrip("+") for f in feature_flags.split(",") if not f.startswith("-")
    ]
    expected_cpu_flags = [
        f
        for f in expected_cpu_flags
        if f and f != "ctr-static"  # Not actually a CPU flag.
    ]

    if not expected_cpu_flags or os.environ.get("POLARS_SKIP_CPU_CHECK"):
        return

    supported_cpu_flags = _read_cpu_flags()

    missing_features = []
    for f in expected_cpu_flags:
        if f not in supported_cpu_flags:
            msg = f"unknown feature flag: {f!r}"
            raise RuntimeError(msg)

        if not supported_cpu_flags[f]:
            missing_features.append(f)

    if missing_features:
        import warnings  # Only import if necessary.

        warnings.warn(
            f"""Missing required CPU features.

The following required CPU features were not detected:
    {", ".join(missing_features)}
Continuing to use this version of Polars on this processor will likely result in a crash.
Install `polars[rtcompat]` instead of `polars` to run Polars with better compatibility.

Hint: If you are on an Apple ARM machine (e.g. M1) this is likely due to running Python under Rosetta.
It is recommended to install a native version of Python that does not run under Rosetta x86-64 emulation.

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 polars`
2. Verify all polars packages share one version: `pip list | grep -i polars`
3. As a stopgap set `POLARS_SKIP_CPU_CHECK=1` — the env check happens before the flag loop, so the unknown-flag validation is bypassed (update properly afterwards)

Example fix

# before: mixed install, e.g. polars 1.40 with polars-runtime-64 from 1.45
import polars as pl  # RuntimeError: unknown feature flag: 'avx512'

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

import importlib.metadata as md

try:
    plr_ver = md.version("polars")
    for rt in ("polars-runtime-compat", "polars-runtime-64", "polars-runtime-32"):
        try:
            if md.version(rt) != plr_ver:
                raise RuntimeError(f"{rt} {md.version(rt)} != polars {plr_ver} — clean reinstall required")
        except md.PackageNotFoundError:
            pass
except md.PackageNotFoundError:
    pass

try:
    import polars as pl
except RuntimeError as e:
    if "unknown feature flag" in str(e):
        raise SystemExit("polars install is version-mixed — run: pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32 && pip install polars")
    raise

When it happens

Trigger: Import-time: a `_polars_runtime_compat`/`_polars_runtime_64`/`_polars_runtime_32` wheel from a different polars release lingers in site-packages after `pip install -U polars`, or a mixed pip/conda install, so BUILD_FEATURE_FLAGS contains a flag name this polars version cannot map.

Common situations: Upgrading polars without cleanly replacing the split runtime packages; CI layer caching old wheels; mixing conda-forge and PyPI installs; using POLARS_PREFER_PKG/FORCE with a runtime package from another version.

Related errors

• Polars Rust module for '{_force}' ({sys.modules[__name__].__
• could not find Polars' Rust module
• could not allocate memory for CPUID check
• could not execute mprotect for CPUID check
• {prefix}'{module_name}'{suffix}. Please install using the co

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