{"record":{"id":"b87a190296e8ce6a","repo":"pola-rs/polars","slug":"unknown-feature-flag-f-r","errorCode":null,"errorMessage":"unknown feature flag: {f!r}","messagePattern":"unknown feature flag: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"py-polars/src/polars/_cpu_check.py","lineNumber":263,"sourceCode":"    expected_cpu_flags = [\n        f.lstrip(\"+\") for f in feature_flags.split(\",\") if not f.startswith(\"-\")\n    ]\n    expected_cpu_flags = [\n        f\n        for f in expected_cpu_flags\n        if f and f != \"ctr-static\"  # Not actually a CPU flag.\n    ]\n\n    if not expected_cpu_flags or os.environ.get(\"POLARS_SKIP_CPU_CHECK\"):\n        return\n\n    supported_cpu_flags = _read_cpu_flags()\n\n    missing_features = []\n    for f in expected_cpu_flags:\n        if f not in supported_cpu_flags:\n            msg = f\"unknown feature flag: {f!r}\"\n            raise RuntimeError(msg)\n\n        if not supported_cpu_flags[f]:\n            missing_features.append(f)\n\n    if missing_features:\n        import warnings  # Only import if necessary.\n\n        warnings.warn(\n            f\"\"\"Missing required CPU features.\n\nThe following required CPU features were not detected:\n    {\", \".join(missing_features)}\nContinuing to use this version of Polars on this processor will likely result in a crash.\nInstall `polars[rtcompat]` instead of `polars` to run Polars with better compatibility.\n\nHint: If you are on an Apple ARM machine (e.g. M1) this is likely due to running Python under Rosetta.\nIt is recommended to install a native version of Python that does not run under Rosetta x86-64 emulation.\n","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_cpu_check.py#L245-L281","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["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`","Verify all polars packages share one version: `pip list | grep -i polars`","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)"],"exampleFix":"# before: mixed install, e.g. polars 1.40 with polars-runtime-64 from 1.45\nimport polars as pl  # RuntimeError: unknown feature flag: 'avx512'\n\n# after: realign versions\n# pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32\n# pip install --upgrade polars\nimport polars as pl","handlingStrategy":"validation","validationCode":"import importlib.metadata as md\n\ntry:\n    plr_ver = md.version(\"polars\")\n    for rt in (\"polars-runtime-compat\", \"polars-runtime-64\", \"polars-runtime-32\"):\n        try:\n            if md.version(rt) != plr_ver:\n                raise RuntimeError(f\"{rt} {md.version(rt)} != polars {plr_ver} — clean reinstall required\")\n        except md.PackageNotFoundError:\n            pass\nexcept md.PackageNotFoundError:\n    pass","typeGuard":null,"tryCatchPattern":"try:\n    import polars as pl\nexcept RuntimeError as e:\n    if \"unknown feature flag\" in str(e):\n        raise SystemExit(\"polars install is version-mixed — run: pip uninstall -y polars polars-runtime-compat polars-runtime-64 polars-runtime-32 && pip install polars\")\n    raise","preventionTips":["Never mix polars wheels from different releases; upgrade with `pip install -U polars` and let it replace runtime packages","After upgrades, verify `pip list | grep -i polars` shows one identical version across all polars packages","Avoid mixing pip and conda installs of polars in one environment","Don't cache old polars-runtime-* wheels in Docker layers or CI caches across polars upgrades"],"tags":["version-mismatch","import-time","wheels","cpu-flags","packaging"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}