Polars · Module

.str.split

Splits string values in a Polars expression around a delimiter and produces a list of string fragments. The delimiter is literal by default, with options for retaining it or interpreting it as regex.

How it works

Use this expression in a Polars pipeline to split each string value at occurrences of a delimiter. By default the delimiter is treated literally; optional flags control whether it is retained and how regex patterns are handled.

Syntax

Expr.str.split(by: IntoExpr, *, inclusive: bool = False, literal: bool = True, strict: bool = True) → Expr

Parameters

Name	Type	Description
`by`	`IntoExpr`	Substring or expression used as the separator.
`inclusive`	`bool = False`	Include the separator in the results when true.
`literal`	`bool = True`	Interpret `by` as a literal string instead of a regular expression.
`strict`	`bool = True`	Control handling of invalid regular expressions; raise when true, otherwise use null.

Returns

Expr producing string-list values.

Key points

Splits each string value wherever the specified separator occurs.
Set inclusive=True when each resulting piece should retain the separator.
The default treats the separator as plain text rather than regex syntax.
The method returns a Polars expression producing string-list values.

Common mistakes

With the default literal mode, regex metacharacters in by are not interpreted as patterns.
When regex mode is enabled, an invalid pattern either raises an error or produces null depending on strict.

Example: Split strings into lists

import polars as pl

df = pl.DataFrame({"s": ["foo bar", "foo-bar", None]})
result = df.select(
    pl.col("s").str.split(by=" ").alias("parts")
)
print(result)

Creates a list column by splitting each string on a literal space.

When to use it

Tokenize text

Convert delimited text columns into list-valued columns for later list operations.

Decompose fields

Separate structured identifiers such as paths, tags, or compound keys.

Pattern-based splitting

Use regex separators when delimiters vary and pattern matching is needed.

Interview questions

QWhat does Expr.str.split do, and what does it return?

str.split splits string values by the supplied by expression and returns an expression whose values are lists of strings. The delimiter is literal by default.

Follow-up: How would you preserve the delimiter? Pass inclusive=True, which includes the split string in the resulting pieces.

QExplain the main arguments of str.split.

by is the substring or expression used as the separator. inclusive controls whether that separator is included, while literal determines whether by is interpreted literally or as a regular expression.

Follow-up: What happens with an invalid regex? With strict=True it raises an error; with strict=False the invalid pattern is masked with null.

QHow would you use str.split in a DataFrame transformation?

The expression is suitable for use in a lazy or eager Polars expression pipeline, such as select or with_columns. The resulting expression has string-list output values.

Follow-up: When a fixed number of fields is required instead, which related operation is more appropriate? Use str.splitn or str.split_exact depending on whether a bounded remainder or an exact number of splits is needed.

Expr.str.splitn
Expr.str.split_exact
Series.str.split_exact

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