pola-rs/polars · error · ModuleUpgradeRequiredError

a more recent version of `fastexcel` is required for 'use_co

Error message

a more recent version of `fastexcel` is required for 'use_columns' (>= 0.10.2; found {original_version})

What it means

Raised as ModuleUpgradeRequiredError in _read_spreadsheet_calamine when read_options contains 'use_columns' and the installed fastexcel is older than 0.10.2. The key is set automatically whenever you pass the top-level `columns` parameter to read_excel with the calamine engine, and can also be supplied directly. Note the gap: fastexcel 0.10.0/0.10.1 pass the bytes check (error 427) but still fail here.

Source

Thrown at py-polars/src/polars/io/spreadsheet/functions.py:1051

    read_options: dict[str, Any],
    schema_overrides: SchemaDict | None,
    columns: Sequence[int] | Sequence[str] | None,
    table_name: str | None = None,
    drop_empty_rows: bool,
    drop_empty_cols: bool,
    raise_if_empty: bool,
) -> pl.DataFrame:
    # if we have 'schema_overrides' and a more recent version of `fastexcel`
    # we can pass translated dtypes to the engine to refine the initial parse
    fastexcel = import_optional("fastexcel")
    fastexcel_version = parse_version(original_version := fastexcel.__version__)

    if fastexcel_version < (0, 9) and "schema_sample_rows" in read_options:
        msg = f"a more recent version of `fastexcel` is required for 'schema_sample_rows' (>= 0.9; found {original_version})"
        raise ModuleUpgradeRequiredError(msg)
    if fastexcel_version < (0, 10, 2) and "use_columns" in read_options:
        msg = f"a more recent version of `fastexcel` is required for 'use_columns' (>= 0.10.2; found {original_version})"
        raise ModuleUpgradeRequiredError(msg)
    if table_name and fastexcel_version < (0, 12):
        msg = f"a more recent version of `fastexcel` is required for 'table_name' (>= 0.12.0; found {original_version})"
        raise ValueError(msg)

    if columns:
        if not isinstance(columns, list):
            columns = list(columns)  # type: ignore[assignment]
        read_options["use_columns"] = columns

    schema_overrides = schema_overrides or {}
    if read_options.get("schema_sample_rows") == 0:
        # ref: https://github.com/ToucanToco/fastexcel/issues/236
        del read_options["schema_sample_rows"]
        read_options["dtypes"] = (
            "string"
            if fastexcel_version >= (0, 12, 1)
            else dict.fromkeys(range(16384), "string")
        )

View on GitHub (pinned to df599052da)

Solutions

1. Upgrade fastexcel to >= 0.10.2
2. No upgrade possible: read all columns and select afterwards — df = pl.read_excel(src)[['a','c']] or df.select(columns)
3. Or use engine='openpyxl'/'xlsx2csv', which handle columns independent of the fastexcel version

Example fix

# before (fastexcel < 0.10.2)
df = pl.read_excel(src, columns=['a', 'c'])

# after (no upgrade)
df = pl.read_excel(src).select('a', 'c')

def fastexcel_at_least(major, minor, patch=0) -> bool:
    import fastexcel
    return tuple(int(p) for p in fastexcel.__version__.split('.')[:3]) >= (major, minor, patch)

columns = ['a', 'c'] if fastexcel_at_least(0, 10, 2) else None
df = pl.read_excel(src, columns=columns)
if columns is None:
    df = df.select('a', 'c')  # post-select on old fastexcel

from polars.exceptions import ModuleUpgradeRequiredError
try:
    df = pl.read_excel(src, columns=cols)
except ModuleUpgradeRequiredError as e:
    if "'use_columns'" in str(e):
        df = pl.read_excel(src).select(cols)  # fallback: select after full read
    else:
        raise

When it happens

Trigger: pl.read_excel(src, columns=['a','c']) with fastexcel < 0.10.2 (columns is rewritten into read_options['use_columns']); or read_options={'use_columns': [0, 2]} passed explicitly with an older fastexcel.

Common situations: Environments pinned to fastexcel 0.9–0.10.1 (e.g. to satisfy the schema_sample_rows floor); code that read full sheets fine until someone added column selection.

Related errors

• `fastexcel` >= 0.10 is required to read bytes; found {module
• a more recent version of `fastexcel` is required for 'schema
• a more recent version of `fastexcel` is required for 'table_
• cannot specify both `columns` and `read_options["columns"]`
• file {source.name!r} must be opened in binary mode

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