What causes "Invalid value for `POLARS_FORCE_PKG` variable: '{_force}'" in pola-rs/polars?

Set the variable to a valid key: `export POLARS_FORCE_PKG=compat` (or '64'/'32')

Invalid value for `POLARS_FORCE_PKG` variable: '{_force}'

Error message

Invalid value for `POLARS_FORCE_PKG` variable: '{_force}'

What it means

POLARS_FORCE_PKG selects which bundled Rust runtime polars loads; the only valid values are the dict keys 'compat', '64', and '32' (mapping to the `_polars_runtime_compat`/`_polars_runtime_64`/`_polars_runtime_32` packages). Any other string causes a KeyError that is re-raised as this ValueError at import time.

Source

Thrown at py-polars/src/polars/_plr.py:65

    # 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:
                    import warnings

                    version_warnings += [sys.modules[__name__].__version__]

View on GitHub (pinned to df599052da)

Solutions

Set the variable to a valid key: `export POLARS_FORCE_PKG=compat` (or '64'/'32')
Or unset it (`unset POLARS_FORCE_PKG`) to use default auto-selection
Check for stray whitespace/quotes: `printf '[%s]\n' "$POLARS_FORCE_PKG"`

Example fix

# before
# POLARS_FORCE_PKG=cpu64
import polars as pl  # ValueError: Invalid value for `POLARS_FORCE_PKG` variable: 'cpu64'

# after
# POLARS_FORCE_PKG=compat  (or '64'/'32')
import polars as pl

Defensive patterns

Strategy: validation

Validate before calling

import os

force = os.environ.get("POLARS_FORCE_PKG")
if force is not None and force not in {"compat", "64", "32"}:
    raise RuntimeError(f"POLARS_FORCE_PKG={force!r} invalid — must be one of compat/64/32 or unset")

Type guard

import os

def valid_force_pkg(value: str | None) -> bool:
    return value is None or value in {"compat", "64", "32"}

Try / catch

try:
    import polars as pl
except ValueError as e:
    if "POLARS_FORCE_PKG" in str(e):
        import os; del os.environ["POLARS_FORCE_PKG"]
        import polars as pl  # noqa
    else:
        raise

Prevention

Validate both POLARS_FORCE_PKG and POLARS_PREFER_PKG against {'compat','64','32'} in a startup config check
Strip whitespace when loading env files (python-dotenv users see trailing-space bugs often)
Document the valid values next to wherever you set the variable (CI yaml, Dockerfile, .env)

When it happens

Trigger: `POLARS_FORCE_PKG=cpu64 python -c "import polars"`, or any value outside {'compat','64','32'} — including trailing whitespace from .env files (`POLARS_FORCE_PKG='64 '`) and shell quoting mistakes.

Common situations: Copy-pasting the variable from outdated blog posts or docs describing older polars mechanisms; typos; whitespace introduced by YAML/.env interpolation.

Related errors

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