Polars when-then-otherwise: Conditional Expressions in Python
Learn how to use Polars when-then-otherwise expressions to create conditional columns, chain multiple conditions, and handle type and null edge cases.

When you need to apply conditional logic to a Polars DataFrame, when-then-otherwise is the primary tool. It behaves like a vectorized if-elif-else that operates on entire columns, avoiding Python-level loops. This article covers the syntax, common patterns, and practical considerations for using conditional expressions in Polars.
Basic Syntax of when-then-otherwise
The core structure is pl.when(condition).then(value).otherwise(value). The condition is a boolean expression evaluated element-wise, and the then and otherwise branches can be literals, column references, or other expressions.
import polars as pl
df = pl.DataFrame({
"score": [45, 78, 92, 61, 30],
})
df.with_columns(
pl.when(pl.col("score") >= 60)
.then("pass")
.otherwise("fail")
.alias("result")
)This adds a result column where each row gets "pass" if the score is at least 60, otherwise "fail". The expression is evaluated column-wise, so Polars processes data in chunks and avoids Python-level row iteration.
Chaining Multiple Conditions with then
For more than two outcomes, chain additional .when() calls after a .then(). This mirrors an elif chain. The first matching condition determines the result; in the final output, later branches only affect rows that did not match earlier conditions. Internally, Polars still applies the branches as columnar expressions, so this is not a row-by-row Python short-circuit.
df.with_columns(
pl.when(pl.col("score") >= 90)
.then("A")
.when(pl.col("score") >= 75)
.then("B")
.when(pl.col("score") >= 60)
.then("C")
.otherwise("F")
.alias("grade")
)Order matters. If you reverse the thresholds, the logic breaks because the first condition catches rows that should fall into a later bucket. This is a common source of bugs, especially when thresholds overlap.
Using Conditions Across Multiple Columns
Conditions can reference any number of columns. For example, you might classify rows based on both a numeric threshold and a categorical flag.
df = pl.DataFrame({
"user": ["alice", "bob", "carol"],
"age": [25, 17, 32],
"is_student": [True, True, False],
})
df.with_columns(
pl.when((pl.col("age") < 18) | (pl.col("is_student")))
.then("discount")
.otherwise("standard")
.alias("ticket_type")
)Combine conditions with & (and), | (or), and ~ (not). Parentheses are required around each comparison because Python evaluates bitwise operators like | before comparison operators; wrap each condition in parentheses to avoid ambiguity.
Using when-then-otherwise Inside Other Expressions
A when-then-otherwise expression can be nested inside other Polars expressions, such as aggregation functions. For example, you can use it inside pl.sum to perform conditional aggregation.
df = pl.DataFrame({
"category": ["A", "B", "A", "B"],
"value": [10, 20, 30, 40],
})
df.group_by("category").agg(
pl.sum(pl.when(pl.col("value") > 15).then(pl.col("value")).otherwise(0)).alias("sum_over_15")
)Here, pl.sum receives an expression that returns the original value only when it exceeds 15, otherwise zero. This avoids filtering rows and then aggregating separately and keeps the logic in one expression.
Performance Considerations
Because when-then-otherwise is a vectorized expression, it avoids Python-level row iteration. In a LazyFrame, it is part of the query plan and can be optimized before execution. For large DataFrames, this is generally faster than using apply or a list comprehension.
One nuance: chained .when() calls are not implemented as a row-level short-circuit. The logic is applied through columnar masks, so do not expect Python-style behavior where later conditions are skipped for rows that already matched. This is still efficient for typical workloads, but if you have many conditions, the intermediate masks can add memory overhead. Keep the number of conditions reasonable.
Common Pitfalls and How to Avoid Them
Missing otherwise
If you omit .otherwise(), rows that do not match any condition become null. This is sometimes intentional, but often a bug. Always verify whether nulls are acceptable in the output column.
# This yields null for scores below 60
df.with_columns(
pl.when(pl.col("score") >= 60).then("pass").alias("result")
)Mixing Data Types
The then and otherwise branches must produce the same data type, or Polars will attempt to cast. If you use an integer in one branch and a string in another, you may get an error or an unexpected cast. For example, .then(1).otherwise("no") will fail because Polars cannot unify Int64 and String automatically. Use .cast(pl.Utf8) or choose consistent types.
Using Python if Instead of when
A common mistake is trying to use a Python if statement inside a select or with_columns. That does not work because if is evaluated once at the expression-building stage, not per row. Always use pl.when for row-wise conditional logic.
Advanced Pattern: Conditional Column with Multiple Branches and Null Handling
Sometimes you need to handle nulls explicitly. You can use pl.when(pl.col("value").is_null()) as a condition to assign a default, then chain other conditions.
df = pl.DataFrame({
"value": [None, 5, 12, None, 20],
})
df.with_columns(
pl.when(pl.col("value").is_null())
.then(pl.lit("missing"))
.when(pl.col("value") < 10)
.then("low")
.otherwise("high")
.alias("bucket")
)This produces "missing" for nulls, "low" for values under 10, and "high" otherwise. Every branch must use the same data type. If you used .then(0) for the null branch while "low" and "high" are strings, Polars would not be able to combine those branches into one column.
Using when-then-otherwise with pl.col and pl.lit for Dynamic Values
The then and otherwise branches can also be expressions that reference other columns. This allows you to copy values conditionally.
df = pl.DataFrame({
"a": [1, 2, 3],
"b": [10, 20, 30],
})
df.with_columns(
pl.when(pl.col("a") > 1)
.then(pl.col("b"))
.otherwise(pl.lit(0))
.alias("c")
)Here, column c gets the value of b when a is greater than 1, otherwise 0. This is a common pattern for applying business rules that depend on multiple columns.
For literals, pl.lit is not always required; Polars accepts Python literals directly in then and otherwise. However, when you need to combine a literal with an expression (for example, pl.col("b") * 2), you can write that directly as an expression.
Compatibility with LazyFrames and Streaming
when-then-otherwise works on LazyFrame as well as on DataFrame. In a LazyFrame, select and with_columns add to the query plan and run when you call collect(). In an eager DataFrame, these methods execute immediately. In both cases, the conditional logic is vectorized rather than row-by-row.
Streaming support depends on the Polars version. If you use streaming execution, check the Polars documentation for the version you are using; the supported expression set can change between releases.
Final Thoughts on Structuring Complex Conditional Logic
When you find yourself chaining many .when() calls, consider whether the logic can be expressed more clearly with a mapping or a separate function. For example, if you are assigning categories based on a numeric range, a cut or binning utility might be more appropriate. However, for arbitrary boolean conditions, when-then-otherwise remains the most direct tool.
Another maintainability tip: name your conditions or use intermediate expressions. Polars allows you to define an expression as a variable and reuse it.
high_score = pl.col("score") >= 90
medium_score = pl.col("score") >= 70
df.with_columns(
pl.when(high_score).then("high")
.when(medium_score).then("medium")
.otherwise("low")
.alias("level")
)This makes the logic easier to read and modify. The same expression objects can be reused across multiple with_columns calls if needed.
Finally, remember that when-then-otherwise returns a Polars expression that can be used wherever an expression of the resulting type is accepted. This includes select, with_columns, group_by aggregations, and sort keys. It can also be used in filter when the branches produce a boolean result. Understanding this flexibility lets you solve many data transformation problems without resorting to Python loops or user-defined functions.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.