Invalid value for `POLARS_PREFER_PKG` variable: '{_prefer}'

Error message

Invalid value for `POLARS_PREFER_PKG` variable: '{_prefer}'

What it means

POLARS_PREFER_PKG moves one Rust runtime package to the front of the preference list polars tries at import; valid values are the dict keys 'compat', '64', '32'. Any other value causes a KeyError when indexing `pkgs[_prefer]`, re-raised as this ValueError at import time. Unlike FORCE, an invalid PREFER fails immediately rather than falling back to defaults.

Source

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

    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__]
                    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

View on GitHub (pinned to df599052da)

Solutions

Set the variable to a valid key: `export POLARS_PREFER_PKG=64` (or 'compat'/'32')
Or unset it (`unset POLARS_PREFER_PKG`) to keep the default preference order compat -> 64 -> 32
Echo the raw value to catch whitespace/quotes: `printf '[%s]\n' "$POLARS_PREFER_PKG"`

Example fix

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

# after
# POLARS_PREFER_PKG=64
import polars as pl

Defensive patterns

Strategy: validation

Validate before calling

import os

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

Type guard

import os

def valid_prefer_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_PREFER_PKG" in str(e):
        import os; del os.environ["POLARS_PREFER_PKG"]
        import polars as pl  # noqa
    else:
        raise

Prevention

Run a startup env sanitizer that whitelists POLARS_* variables and their values
Watch CI matrix interpolations that can produce empty or invalid values for POLARS_PREFER_PKG
Prefer unset (default order compat -> 64 -> 32) unless a specific variant is required

When it happens

Trigger: `POLARS_PREFER_PKG=x86_64 python -c "import polars"` or any value outside {'compat','64','32'}, including whitespace or quoting artifacts from environment files or CI matrix variables.

Common situations: Env vars carried over from older polars versions or other projects; CI configuration with interpolated values that expand to empty/invalid strings; typos.

Related errors

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