LearnContact
Lesson 2026 min read

Match-Case Statement

Learn how Python's match-case statement provides structural pattern matching as a modern alternative to long if-elif chains.

Introduction

Python 3.10 introduced the match statement, which provides structural pattern matching — a modern, often cleaner alternative to writing long chains of if/elif statements when comparing one value against many possibilities.

If you have used a "switch" statement in languages like C, Java, or JavaScript, match-case will feel familiar, though Python's version is more powerful because it can also match the shape or structure of data, not just simple values.

What You Will Learn
  • The basic syntax of match and case (Python 3.10+).
  • How to match literal values and use the wildcard case (_).
  • How to match multiple values in a single case using |.
  • How to match simple patterns like tuples and destructure them.
  • How to add guard clauses with if inside a case.
  • How match-case compares to if/elif chains and switch statements.
Version Requirement

The match statement requires Python 3.10 or later. If you are using an older version of Python, this feature is not available and you must use if/elif instead.

Basic Syntax

A match statement takes a value (called the "subject") and compares it against a series of case patterns, running the code under the first pattern that matches.

match_syntax.py
day = "Mon"

match day:
    case "Mon":
        print("Start of the work week.")
    case "Fri":
        print("Almost the weekend!")
    case "Sat":
        print("Weekend!")
Output
Start of the work week.

Matching Literal Values

The simplest use of match is comparing against literal values, such as strings or numbers, just like a chain of equality checks.

literal_matching.py
status_code = 404

match status_code:
    case 200:
        print("OK")
    case 404:
        print("Not Found")
    case 500:
        print("Server Error")
Output
Not Found

The Wildcard Case (_)

The underscore _ acts as a catch-all pattern that matches anything, similar to a default or else branch. It should always come last, since match checks cases in order.

wildcard_case.py
status_code = 302

match status_code:
    case 200:
        print("OK")
    case 404:
        print("Not Found")
    case _:
        print("Unhandled status code:", status_code)
Output
Unhandled status code: 302
No Matching Case, No Wildcard

If none of the case patterns match and there is no wildcard (_), the match statement simply does nothing — it does not raise an error.

Matching Multiple Values with |

Use the pipe symbol | inside a case to match several possible values with a single block of code, avoiding repetition.

multiple_values.py
day = "Sat"

match day:
    case "Sat" | "Sun":
        print("It's the weekend!")
    case "Mon" | "Tue" | "Wed" | "Thu" | "Fri":
        print("It's a weekday.")
    case _:
        print("Not a valid day.")
Output
It's the weekend!

Matching Patterns (Destructuring)

match can also inspect the structure of a value, such as a tuple, and pull its parts into variables in a single step — this is called destructuring.

pattern_destructuring.py
point = (0, 5)

match point:
    case (0, 0):
        print("Origin")
    case (0, y):
        print(f"On the y-axis at y={y}")
    case (x, 0):
        print(f"On the x-axis at x={x}")
    case (x, y):
        print(f"Point at ({x}, {y})")
Output
On the y-axis at y=5

In the pattern (0, y), the 0 must match exactly, while y acts as a variable that captures whatever value is in that position — no manual indexing required.

Guard Clauses with if

A guard clause adds an extra condition to a case using if. Even if the pattern itself matches, the case only runs when the guard condition is also True.

guard_clause.py
point = (4, 4)

match point:
    case (x, y) if x == y:
        print("Point is on the diagonal.")
    case (x, y) if x > y:
        print("X is greater than Y.")
    case (x, y):
        print("Y is greater than or equal to X.")
Output
Point is on the diagonal.

match-case vs if/elif vs switch

match-case and if/elif can often solve the same problem, but each shines in different situations.

if / elif

  • Best for range checks and complex boolean logic.
  • Works in every Python version.
  • Can become long and repetitive for many exact-value checks.

match / case

  • Best for comparing one value against many exact possibilities or shapes.
  • Requires Python 3.10+.
  • Can destructure tuples, lists, and objects directly in the pattern.

switch (other languages)

  • Common in C, Java, and JavaScript for matching literal values.
  • Usually cannot destructure data structures like match can.
  • Python did not have this until match was added in 3.10.

Common Mistakes

Avoid These Mistakes
  • Forgetting that match requires Python 3.10 or later.
  • Placing the wildcard case (_) before other cases — it will always match first and the rest become unreachable.
  • Assuming an unmatched value raises an error — without a wildcard, match simply does nothing.
  • Confusing a bare name in a pattern (like y) with a literal value — a bare lowercase name always captures, it does not compare against an existing variable of the same name.
  • Overusing match for simple True/False checks where a plain if is clearer.

Best Practices

  • Always place the wildcard case (_) last.
  • Use match when comparing one value against several exact options or structural shapes.
  • Use guard clauses (case pattern if condition) for extra fine-grained checks.
  • Keep case bodies short and readable, just like well-written if/elif branches.
  • Stick with if/elif for simple boolean logic or when supporting Python versions older than 3.10.

Frequently Asked Questions

Which Python version added match-case?

Python 3.10, released in 2021, introduced the match statement as part of PEP 634.

Is match-case exactly the same as switch in other languages?

It is similar in spirit but more powerful — Python's match can destructure tuples, lists, and objects, not just compare literal values.

What happens if no case matches and there is no wildcard?

Nothing happens. The match statement completes without running any block and without raising an error.

Can I match against a variable's value instead of always capturing it as a new name?

Yes, but you typically need a guard clause (case x if x == some_variable) or use a dotted name/constant, since a plain lowercase name in a pattern is treated as a capture variable, not a comparison.

Can match-case replace all if/elif chains?

Not always. It excels at matching exact values or structures, but ranges and complex boolean conditions are often still clearer with if/elif.

Key Takeaways

  • match/case (Python 3.10+) compares a subject value against a series of patterns.
  • The wildcard _ acts as a catch-all default case and should always be listed last.
  • The | operator lets one case match multiple values.
  • match can destructure tuples and other structures directly in the pattern.
  • Guard clauses (case pattern if condition) add extra conditions to a case.

Summary

The match-case statement gives Python a modern, expressive way to compare a value against many possibilities, including destructuring structured data, without writing a long chain of if/elif statements.

Next, you will learn about loops — for and while — which let you repeat actions instead of writing the same code over and over.

Lesson 20 Completed
  • You understand match-case syntax and when it was introduced.
  • You can match literals, multiple values, and simple patterns.
  • You can add guard clauses to refine a case.
  • You are ready to learn about loops.
Next Lesson →

Loops (for & while)