Polars · Module

df.partition_by

Groups a DataFrame by one or more columns and returns each group as a separate DataFrame. Choose list output or dictionary output keyed by group-value tuples.

How it works

partition_by groups a DataFrame by one or more columns or selectors and materializes each group as its own DataFrame. It returns an ordered list by default, or a dictionary keyed by tuples of distinct grouping values when as_dict=True; grouping columns remain in each result unless include_key=False.

Syntax

DataFrame.partition_by(by, *more_by, maintain_order=True, include_key=True, as_dict=False)

Parameters

Name	Type	Description
`by`	`ColumnNameOrSelector \| Sequence[ColumnNameOrSelector]`	Column name(s) or selector(s) to group by.
`more_by`	`ColumnNameOrSelector`	Additional names of columns to group by, specified as positional arguments.
`maintain_order`	`bool = True`	Ensure that the order of the groups is consistent with the input data. This is slower than a default partition by operation.
`include_key`	`bool = True`	Include the columns used to partition the DataFrame in the output.
`as_dict`	`bool = False`	Return a dictionary instead of a list. Dictionary keys are tuples of distinct group values.

Returns

list[DataFrame] | dict[tuple[Any, ...], DataFrame]

Key points

The method materializes each group as a separate DataFrame.
The primary grouping argument accepts column names or selectors, including a sequence of them.
Further grouping columns can be supplied as positional arguments after by.
maintain_order requests group ordering consistent with the source DataFrame.
include_key determines whether partitioning columns are retained in each output DataFrame.
as_dict changes the result container from a list to a dictionary.
Dictionary mode identifies each partition with a tuple of its distinct grouping values.

Common mistakes

Setting maintain_order=True preserves the input-derived group order but is slower than the default partition operation.

Example: Partition rows by one column

import polars as pl

df = pl.DataFrame({"team": ["A", "B", "A"], "score": [3, 5, 4]})
parts = df.partition_by("team")

assert len(parts) == 2
assert parts[0].get_column("team").to_list() == ["A", "A"]

Creates one DataFrame per distinct team value while preserving the input order of groups and rows.

When to use it

Split grouped data into separate DataFrames

Downstream processing needs independent tables for each category or tenant.

Build a dictionary of partitions

Code needs direct lookup using composite grouping values.

Preserve group order

Results must follow the order groups first appear in the input.

Remove grouping keys from partitions

Outputs should exclude the columns used solely for partitioning.

Interview questions

QWhat does DataFrame.partition_by do, and what does it return by default?

It separates the DataFrame into one DataFrame per distinct combination of the selected grouping columns. By default, it returns a list and includes the grouping columns in every partition.

Follow-up: How would you retrieve partitions by their group values? Set as_dict=True; the result is keyed by tuples containing the distinct group values.

QHow do you specify one or multiple grouping columns?

Use by for a column name, a sequence of names, or selectors, and use additional positional column names through more_by. For example, partition_by("country", "status") groups by both columns.

Follow-up: How can you partition by all string columns? Pass a string-column selector, such as polars.selectors.string(), as by.

QExplain the main options of partition_by.

maintain_order controls whether group order follows the input data, include_key controls whether grouping columns remain in each output, and as_dict switches the result from a list to a dictionary. The dictionary uses tuples of distinct group values as keys.

Follow-up: What is the trade-off of enabling maintain_order? It preserves input-consistent group order but is slower than the default operation.

polars.DataFrame.group_by
polars.DataFrame.iter_slices
polars.selectors.string

Source: polars.DataFrame.partition_by — Polars documentation. Checked 2026-10-15.