Polars · Module

.qcut

Bins continuous expression values into discrete categories using quantiles. It supports explicit probabilities or a uniform bin count, optional labels, interval closure, duplicate handling, and breakpoint output; the stable documentation marks it deprecated since 2.0.0.

Since: 2.0.0

How it works

Apply qcut to a numeric expression to convert continuous values into quantile-based categorical bins. Pass an integer for uniformly probable bins or explicit probabilities for chosen cut points; optionally name categories, change interval closure, tolerate repeated quantile boundaries, or include each row's upper boundary.

Syntax

Expr.qcut(quantiles: Sequence[float] | int, *, labels: Sequence[str_] | None = None, left_closed: bool = False, allow_duplicates: bool = False, include_breaks: bool = False) → Expr

Parameters

Name	Type	Description
`quantiles`	`Sequence[float] \| int`	Quantile probabilities from 0 to 1, or a positive integer specifying uniformly probable bins.
`labels`	`Sequence[str_] \| None`	Category names; their count must match the resulting categories.
`left_closed`	`bool`	Whether intervals are left-closed rather than right-closed.
`allow_duplicates`	`bool`	Whether duplicate computed quantiles should be dropped instead of raising DuplicateError.
`include_breaks`	`bool`	Whether to include each observation's bin right endpoint.

Returns

Expr of data type Categorical by default, or Struct when include_breaks=True.

Key points

qcut transforms continuous numeric data into discrete quantile-based categories.
quantiles accepts probabilities or a positive bin count.
Provide exactly one label for every resulting category.
Use left_closed to choose left-closed intervals; otherwise intervals are right-closed.
Duplicate boundaries may arise from the data even when requested probabilities are unique.
include_breaks adds each observation's bin endpoint to the output.

Common mistakes

This method is deprecated in the current stable documentation; prefer bin_quantiles() for new code.
Setting include_breaks=True changes the result from categorical values to a struct containing breakpoint information.
Without allow_duplicates=True, repeated computed quantiles can raise DuplicateError.

Example: Create quantile bands

import polars as pl

df = pl.DataFrame({"score": [-2, -1, 0, 1, 2]})
result = df.with_columns(
    pl.col("score")
    .qcut(2, labels=["low", "high"], left_closed=True)
    .alias("band")
)
print(result)

Adds a categorical column containing two quantile-based bands.

When to use it

Scoring bands

Convert a numeric score expression into named low, medium, or high groups for reporting.

Population segmentation

Create approximately equally populated cohorts from a continuous feature.

Boundary auditing

Attach the computed upper bin boundary to every row for downstream inspection.

Interview questions

QWhat does qcut do, and how can its bins be specified?

qcut bins continuous values according to quantiles. An integer requests that many bins with uniform probability, while a sequence supplies quantile probabilities between 0 and 1.

Follow-up: How would you preserve the upper endpoint for each observation? Use include_breaks=True, which returns a struct rather than a categorical result.

QHow do labels and interval closure affect qcut?

labels supplies category names, and its length must equal the number of resulting categories. left_closed=True makes intervals left-closed instead of the default right-closed intervals.

Follow-up: What happens if quantile boundaries coincide? Set allow_duplicates=True to drop duplicate resulting quantiles instead of raising DuplicateError.

QWhat does include_breaks change, and what is qcut's current status?

The expression returns a Categorical result by default. With include_breaks=True, it returns a Struct expression that includes the right endpoint of the bin assigned to each observation.

Follow-up: Which newer APIs should replace qcut? The documentation recommends bin_quantiles() for quantile breakpoints or bin_ranks() for near-equal-sized positional bins.

Expr.bin_quantiles
Expr.bin_ranks
Expr.cut

Source: polars.Expr.qcut — Polars documentation. Checked 2026-10-15.