pola-rs/polars · error · ValueError

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

Error message

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

What it means

Raised in _read_spreadsheet_calamine when the table_name parameter is used with fastexcel older than 0.12.0, because parser.load_table only exists from 0.12. Inconsistently with its sibling checks (432/433), this one is a plain ValueError, NOT a ModuleUpgradeRequiredError — so an `except ModuleUpgradeRequiredError` handler will not catch it. The engine import floor remains 0.7.0, so nothing warns earlier.

Source

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

    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")
        )
    elif schema_overrides and fastexcel_version >= (0, 10):
        parser_dtypes = read_options.get("dtypes", {})
        for name, dtype in schema_overrides.items():

View on GitHub (pinned to df599052da)

Solutions

Upgrade fastexcel to >= 0.12.0 (pip install -U 'fastexcel>=0.12')
If you cannot upgrade, read Excel tables via engine='openpyxl', which supports table_name natively
When catching this, remember it is ValueError — also catch ModuleUpgradeRequiredError separately for the sibling version checks

Example fix

# before (fastexcel 0.10.x)
pl.read_excel(src, table_name='SalesTable')

# after (no fastexcel upgrade available)
pl.read_excel(src, table_name='SalesTable', engine='openpyxl')

Defensive patterns

Strategy: fallback

Validate before calling

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)

engine = 'calamine' if fastexcel_at_least(0, 12) else 'openpyxl'
df = pl.read_excel(src, table_name='Sales', engine=engine)

Try / catch

# NOTE: this check raises plain ValueError, NOT ModuleUpgradeRequiredError
try:
    df = pl.read_excel(src, table_name='Sales')
except ValueError as e:
    if "'table_name'" in str(e) and 'fastexcel' in str(e):
        df = pl.read_excel(src, table_name='Sales', engine='openpyxl')
    else:
        raise

Prevention

Gate table_name usage on fastexcel >= 0.12 at startup and fall back to engine='openpyxl' otherwise
Remember the exception type inconsistency: table_name raises ValueError while sibling checks raise ModuleUpgradeRequiredError — catch both
Encode the version floor in your lockfile rather than handling it at runtime when possible

When it happens

Trigger: pl.read_excel(src, table_name='SalesTable') with fastexcel 0.7.x–0.11.x installed; table_name arriving via a generic kwargs dict into read_excel on an environment with an older fastexcel.

Common situations: Adopting the (relatively new) table_name feature on a project whose lockfile still pins an old fastexcel; CI passing locally (newer env) but failing in prod images.

Related errors

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