pola-rs/polars · error · ValueError

`n_rows` cannot be used with `use_pyarrow=True`

Error message

`n_rows` cannot be used with `use_pyarrow=True`

What it means

pl.read_parquet raises this ValueError when use_pyarrow=True is combined with n_rows. The pyarrow dispatch path (_read_parquet_with_pyarrow) only bridges a subset of read_parquet's parameters; row limiting is implemented solely in polars' native reader, so the combination is rejected up front before any file is opened.

Source

Thrown at py-polars/src/polars/io/parquet/functions.py:232

    Calling `read_parquet().lazy()` is an antipattern as this forces Polars to
    materialize a full parquet file and therefore cannot push any optimizations
    into the reader. Therefore always prefer `scan_parquet` if you want to work
    with `LazyFrame` s.

    """
    if schema is not None:
        msg = "the `schema` parameter of `read_parquet` is considered unstable."
        issue_unstable_warning(msg)

    if hive_schema is not None:
        msg = "the `hive_schema` parameter of `read_parquet` is considered unstable."
        issue_unstable_warning(msg)

    # Dispatch to pyarrow if requested
    if use_pyarrow:
        if n_rows is not None:
            msg = "`n_rows` cannot be used with `use_pyarrow=True`"
            raise ValueError(msg)
        if include_file_paths is not None:
            msg = "`include_file_paths` cannot be used with `use_pyarrow=True`"
            raise ValueError(msg)
        if schema is not None:
            msg = "`schema` cannot be used with `use_pyarrow=True`"
            raise ValueError(msg)
        if hive_schema is not None:
            msg = (
                "cannot use `hive_partitions` with `use_pyarrow=True`"
                "\n\nHint: Pass `pyarrow_options` instead with a 'partitioning' entry."
            )
            raise TypeError(msg)
        return _read_parquet_with_pyarrow(
            source,
            columns=columns,
            storage_options=storage_options,
            pyarrow_options=pyarrow_options,
            memory_map=memory_map,

View on GitHub (pinned to df599052da)

Solutions

1. Drop use_pyarrow (use the default native engine) — it fully supports n_rows and is generally faster.
2. Keep use_pyarrow=True, remove n_rows, and slice afterwards: pl.read_parquet(...).head(1000) (note: the whole file is still decoded).
3. If you were using pyarrow for a specific reason, call pyarrow.parquet.read_table directly with its own row-group/fragment options instead.

Example fix

# before
pl.read_parquet('f.parquet', use_pyarrow=True, n_rows=1000)

# after
pl.read_parquet('f.parquet', n_rows=1000)  # native engine
# or
pl.read_parquet('f.parquet', use_pyarrow=True).head(1000)

kwargs = {'use_pyarrow': True}
if n_rows is not None:
    kwargs.pop('use_pyarrow')  # native engine supports n_rows
pl.read_parquet(path, n_rows=n_rows, **kwargs)

try:
    df = pl.read_parquet(path, use_pyarrow=True, n_rows=n_rows)
except ValueError as e:
    if 'n_rows' in str(e) and 'use_pyarrow' in str(e):
        df = pl.read_parquet(path, use_pyarrow=True).head(n_rows)
    else:
        raise

When it happens

Trigger: pl.read_parquet('f.parquet', use_pyarrow=True, n_rows=1000). Any non-None n_rows (including 0) together with use_pyarrow=True hits the guard in read_parquet's preamble.

Common situations: Enabling use_pyarrow to read files with data types the native engine handled poorly (older polars versions), or to use pyarrow filesystems, while keeping an existing n_rows sampling argument; copying a pyarrow-dataset snippet into code that already limited rows.

Related errors

• `include_file_paths` cannot be used with `use_pyarrow=True`
• `schema` cannot be used with `use_pyarrow=True`
• cannot use `hive_partitions` with `use_pyarrow=True` Hint:
• write_parquet with `use_pyarrow=True` allows only boolean va
• pyarrow is required for converting a pandas dataframe to Pol

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