Python OR Pattern: Combining Match Cases
Combine multiple cases in Python's match statement with the OR pattern using the | operator. Learn syntax, capture rules, guards, and common pitfalls.

Python's match statement supports OR patterns through the | operator. An OR pattern combines several patterns into one case, so different values can share the same body. This feature is part of structural pattern matching, introduced in Python 3.10.
match command:
case 'start' | 'run':
launch()
case 'stop' | 'halt':
shutdown()Here, 'start' and 'run' both trigger launch(), while 'stop' and 'halt' trigger shutdown().
Basic Syntax of the OR Pattern
The OR pattern uses | between two or more alternatives. The whole group is treated as a single case. The subject is matched against each alternative in order, and the first successful match determines the outcome.
match value:
case 0 | 1:
print('binary digit')
case 2 | 4 | 6 | 8:
print('even digit')
case _:
print('other')You can chain more than two alternatives.
Matching Literal Values with OR
The most common use is combining literal values: strings, numbers, booleans, or None.
def handle_status(status):
match status:
case 200 | 201 | 204:
print('success')
case 400 | 404 | 500:
print('error')
case _:
print('unknown')Each alternative must be a valid pattern. A bare name is not a literal comparison; it is a capture pattern. To match a variable's value, use a guard or a value pattern that uses a dotted name, such as Config.start.
Combining Class Patterns
OR patterns also work with class patterns, letting you combine different types or attribute values in one case.
class Point:
def __init__(self, x, y):
self.x = x
self.y = y
match obj:
case Point(x=0, y=0) | Point(x=0, y=1):
print('origin or adjacent')
case Point(x=0, y=_):
print('on y-axis')
case _:
print('other')When you combine class patterns, all alternatives must bind the same set of names. If one alternative binds x and another binds y, Python rejects the pattern because the body could not rely on a consistent binding.
Using OR with Capture Patterns and Guards
A capture pattern binds the matched value to a name. When you use capture patterns in an OR pattern, each alternative must bind the same names.
match value:
case [x] | [x, _]:
print(f'one or two elements, first is {x}')Both alternatives bind x, so the body can use it. _ is a wildcard and does not bind a name.
Guards are evaluated after the pattern itself matches. Use or and parentheses for boolean logic in a guard, not |:
match point:
case (x, y) if (x > 0) or (y > 0):
print('at least one coordinate is positive')The expression x > 0 | y > 0 would not mean what you expect. Because | binds more tightly than comparison operators, Python parses it as x > (0 | y) > 0, not (x > 0) or (y > 0).
Common Pitfalls and Limitations
A bare name in a pattern is a capture pattern, not a value lookup. A single case allowed: would always match and bind the subject to allowed; it would not compare against the variable's value. Combining it with a literal is also invalid, not a comparison with allowed:
allowed = 'start'
match command:
case allowed | 'run':
launch()The OR pattern's alternatives bind different names (allowed binds, 'run' does not), so Python rejects it. To compare against a variable, use a guard:
allowed = 'start'
match command:
case value if value == allowed or value == 'run':
launch()Or, when the value is a class attribute, use a value pattern:
class Allowed:
start = 'start'
match command:
case Allowed.start | 'run':
launch()Similarly, OR patterns must bind consistent names. case [x | y] is invalid because the two alternatives bind different names; use a guard or restructure the logic if you need to distinguish those cases.
Maintainability and Alternative Approaches
OR patterns let you avoid repeating the same body for several values. With a small number of alternatives, the pattern is easy to read. If the set of values is large or changes frequently, a dictionary mapping may be easier to maintain:
handlers = {
200: handle_success,
201: handle_success,
204: handle_success,
400: handle_error,
}Use OR patterns when the alternatives are few and the action is identical; use a mapping or separate cases when the logic becomes dynamic or each alternative needs different handling.
When to Prefer Separate Cases Over OR Patterns
Separate case clauses are clearer when alternatives need different guards or bind different names.
match value:
case 0:
print('zero')
case 1:
print('one')
case _:
print('other')If the actions are identical and the alternatives are simple, OR patterns are more concise. If the actions differ, or an OR pattern would need inconsistent variable bindings, use separate cases.
Finally, remember that | inside a pattern is the OR-pattern separator, while | inside a guard expression is bitwise OR. For boolean conditions in guards, use or with parentheses.
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.