pola-rs/polars · error · ModuleUpgradeRequiredError

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

Error message

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

What it means

Raised by the calamine reader path when read_options contains 'schema_sample_rows' but the installed fastexcel version is older than 0.9, which introduced that option. Upgrade fastexcel to use schema sampling.

Source

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

    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 5d8ebabf11)

Solutions

1. Upgrade fastexcel to >= 0.9 to use schema_sample_rows.

When it happens

Trigger: Thrown at py-polars/src/polars/io/spreadsheet/functions.py:1051 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of pola-rs/polars@5d8ebabf11 (2026-08-19). Data as JSON: /api/errors/f1d524b3fe6f790a. Report an issue: GitHub.