Polars · Module

df.collect

Materializes a LazyFrame's deferred query plan into a DataFrame. You can select the execution engine, run in the background, and configure query optimizations.

How it works

A LazyFrame records a query plan without immediately executing it. Calling collect materializes that plan into a DataFrame, choosing the execution engine and optimization settings through keyword arguments.

Syntax

LazyFrame.collect(*, engine: EngineType = 'auto', background: bool = False, optimizations: QueryOptFlags = (), **_kwargs: Any) → DataFrame | InProcessQuery

Parameters

Name	Type	Description
`engine`	`EngineType = 'auto'`	Selects the execution engine; supported values include auto, in-memory, streaming, and gpu.
`background`	`bool = False`	Runs collection in the background and returns an in-process query handle.
`optimizations`	`QueryOptFlags = ()`	Configures the query optimization flags used during collection.
`**_kwargs`	`Any`	Accepts additional keyword arguments.

Returns

DataFrame | InProcessQuery

Key points

collect turns a deferred LazyFrame plan into a concrete DataFrame.
The engine argument chooses how the query is executed and defaults to auto.
With auto, engine affinity can come from Polars configuration or the POLARS_ENGINE_AFFINITY environment variable.
Streaming execution handles queries in batches and can reduce memory pressure.
GPU execution requires an Nvidia GPU together with cudf-polars.
For several lazy plans, polars.collect_all is the related batch-collection API.

Common mistakes

GPU execution is disabled when incompatible optimization settings are enabled.

Example: Collect a lazy query

import polars as pl

lf = pl.LazyFrame({"group": ["a", "b", "a"], "value": [1, 2, 3]})
result = (
    lf.group_by("group")
    .agg(pl.col("value").sum())
    .collect(engine="in-memory")
)
print(result)

Builds a lazy aggregation plan and materializes it as an in-memory DataFrame.

When to use it

Materialize a finished query

Turn a composed lazy transformation pipeline into a DataFrame for inspection or downstream Python code.

Stream larger-than-memory workloads

Process a dataset in batches when an in-memory execution plan would create excessive memory pressure.

Use GPU execution

Run supported lazy computations on CUDA hardware with the required Polars GPU integration installed.

Collect in the background

Submit collection without blocking the current control flow when background execution is appropriate.

Interview questions

QWhat does LazyFrame.collect do?

collect executes a LazyFrame's deferred query plan and returns a DataFrame. Its default engine setting is auto, which selects the configured or default execution engine.

Follow-up: How would you reduce memory pressure for a large query? Use the streaming engine, which processes queries in batches.

QWhat execution engines can collect use?

The engine parameter selects execution: auto, in-memory, streaming, or GPU when the required CUDA and cudf-polars support is available. The streaming engine processes data in batches.

Follow-up: What prerequisite is required for GPU execution? The environment needs an Nvidia GPU and cudf-polars.

QHow are optimizations controlled during collection?

collect accepts an optimizations setting that controls query optimization behavior. Individual optimization flags can be configured through QueryOptFlags rather than changing the lazy plan itself.

Follow-up: How can multiple lazy queries be collected together? Use polars.collect_all, which can combine computation graphs and apply common subplan elimination.

polars.collect_all
polars.LazyFrame.collect_async
polars.LazyFrame.explain
polars.LazyFrame.profile

Source: polars.LazyFrame.collect — Polars documentation. Checked 2026-10-15.