Regex match (~, ~*) in Nginx - Deep Dive

Overview - Regex match (~, ~*)

What is it?

In nginx configuration, the tilde symbols ~ and ~* are used to match URLs or strings using regular expressions. The ~ operator performs a case-sensitive match, while ~* performs a case-insensitive match. These operators help nginx decide how to route or handle requests based on patterns in URLs.

Why it matters

Without regex matching in nginx, you would have to write many exact URL rules, which is inefficient and inflexible. Regex matching allows you to handle groups of URLs with patterns, making your server configuration powerful and adaptable. This saves time and reduces errors when managing complex web traffic.

Where it fits

Before learning regex match operators, you should understand basic nginx configuration and how location blocks work. After mastering regex matches, you can explore advanced nginx features like rewrite rules, caching, and load balancing.

Mental Model

Core Idea

The ~ and ~* operators in nginx let you match URL patterns using regular expressions, with ~ being case-sensitive and ~* case-insensitive.

Think of it like...

It's like using a search filter on your phone contacts: ~ is like searching with exact spelling, while ~* lets you find matches regardless of uppercase or lowercase letters.

┌───────────────┐
│ nginx request │
└──────┬────────┘
       │
       ▼
┌───────────────┐       ┌───────────────┐
│ location /abc │       │ location ~ ^/a│
│ (exact match) │       │ regex (case-  │
└───────────────┘       │ sensitive)    │
                        └───────────────┘
       │
       ▼
┌───────────────┐
│ location ~* ^/a│
│ regex (case-  │
│ insensitive)  │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Basic nginx location matching

Concept: Learn how nginx matches URLs using simple location blocks.

In nginx, you define 'location' blocks to specify how to handle requests for certain URLs. For example: location /images/ { # handle requests starting with /images/ } This matches URLs that start exactly with /images/.

Result

nginx routes requests starting with /images/ to this block.

Understanding exact location matching is the base for adding more flexible pattern matching.

2

Foundation

Introduction to regex in nginx

Concept: nginx supports regular expressions to match complex URL patterns.

You can use regex in location blocks by prefixing with ~ or ~*: location ~ ^/images/.*\.jpg$ { # matches URLs ending with .jpg } This uses a regex to match URLs starting with /images/ and ending with .jpg.

Result

nginx matches URLs like /images/pic.jpg but not /images/pic.png.

Regex lets you match patterns that exact strings cannot, increasing flexibility.

3

Intermediate

Difference between ~ and ~* operators

🤔Before reading on: do you think ~ and ~* behave the same or differently? Commit to your answer.

Concept: ~ is case-sensitive regex match; ~* is case-insensitive regex match.

location ~ ^/Images/ { # matches /Images/ but not /images/ } location ~* ^/Images/ { # matches /Images/ and /images/ } The * in ~* means ignore case differences.

Result

~ matches only exact case; ~* matches any case variation.

Knowing the case sensitivity difference prevents unexpected mismatches in URL routing.

4

Intermediate

Order of location matching in nginx

🤔Before reading on: do you think nginx tests regex locations before or after exact matches? Commit to your answer.

Concept: nginx first tries exact and prefix matches, then regex matches in order.

nginx matches locations in this order: 1. Exact match (=) 2. Longest prefix match 3. Regex matches (~ and ~*) in order of appearance If a regex matches, it stops searching further.

Result

Regex locations can override prefix matches if they appear later in config.

Understanding matching order helps avoid conflicts and unexpected routing.

5

Intermediate

Using regex anchors and patterns

Concept: Anchors like ^ and $ define start and end of string in regex patterns.

location ~ ^/api/v1/ { # matches URLs starting exactly with /api/v1/ } location ~* \.php$ { # matches URLs ending with .php, case-insensitive } Anchors ensure precise matching boundaries.

Result

Only URLs matching the pattern exactly at start or end are matched.

Anchors prevent partial matches that could cause wrong routing.

6

Advanced

Performance impact of regex matches

🤔Before reading on: do you think regex matches are faster, slower, or same speed as prefix matches? Commit to your answer.

Concept: Regex matches are slower than prefix matches because they require pattern evaluation.

nginx processes prefix matches quickly by simple string comparison. Regex matches require running the regex engine, which is more CPU intensive. Use regex only when necessary and keep patterns efficient.

Result

Excessive or complex regex can slow down request processing.

Knowing performance costs helps write efficient nginx configs.

7

Expert

Regex caching and internal optimizations

🤔Before reading on: do you think nginx recompiles regex on every request or caches it? Commit to your answer.

Concept: nginx compiles regex patterns once at startup and caches them for fast reuse.

When nginx starts, it compiles all regex patterns in config. During requests, it uses compiled patterns, avoiding recompilation. This caching improves performance but means config reload is needed to change regex.

Result

Regex matching is efficient at runtime but requires reload to update patterns.

Understanding regex compilation lifecycle explains why config reloads are needed after changes.

Under the Hood

nginx uses the PCRE (Perl Compatible Regular Expressions) library to compile and execute regex patterns. When nginx starts, it compiles all regex patterns in location blocks into efficient internal structures. At runtime, when a request arrives, nginx first tries exact and prefix matches using fast string comparisons. If none match, it tests regex locations in order, running the compiled regex against the request URI. The first regex that matches stops the search and handles the request. This layered approach balances speed and flexibility.

Why designed this way?

nginx was designed for high performance and flexibility. Exact and prefix matches are very fast and cover most cases. Regex matching adds power for complex patterns but is slower. By separating these and ordering them, nginx optimizes common cases while still supporting advanced routing. Using PCRE allows nginx to support rich regex syntax familiar to many users. Caching compiled regex avoids runtime overhead but requires reloads to update patterns.

┌───────────────┐
│ nginx startup │
└──────┬────────┘
       │
       ▼
┌─────────────────────────────┐
│ Compile regex patterns (PCRE)│
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│ Request arrives              │
│ ┌─────────────────────────┐ │
│ │ Try exact match (=)      │ │
│ └─────────────┬───────────┘ │
│               │ no match     │
│               ▼             │
│ ┌─────────────────────────┐ │
│ │ Try prefix matches       │ │
│ └─────────────┬───────────┘ │
│               │ no match     │
│               ▼             │
│ ┌─────────────────────────┐ │
│ │ Try regex matches (~,~*) │ │
│ └─────────────┬───────────┘ │
│               │ match       │
│               ▼             │
│ Handle request with matched │
│ location block              │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does ~* match only uppercase letters or both uppercase and lowercase? Commit to your answer.

Common Belief: ~* matches only uppercase letters in URLs.

Reality: ~* matches both uppercase and lowercase letters, ignoring case differences.

Why it matters: Misunderstanding this causes missed matches or unexpected routing failures.

Quick: Does nginx test regex locations before prefix matches? Commit to your answer.

Common Belief: nginx tests regex locations before prefix matches.

Reality: nginx tests exact and prefix matches first, then regex matches in order.

Why it matters: Incorrect assumptions about matching order can cause config conflicts and bugs.

Quick: Does nginx recompile regex patterns on every request? Commit to your answer.

Common Belief: nginx recompiles regex patterns on every request for flexibility.

Reality: nginx compiles regex once at startup and caches them for performance.

Why it matters: Thinking otherwise leads to unnecessary performance concerns and confusion about config reloads.

Quick: Can you use ~ and ~* interchangeably without affecting case sensitivity? Commit to your answer.

Common Belief: ~ and ~* are interchangeable and behave the same.

Reality: ~ is case-sensitive; ~* is case-insensitive, so they behave differently.

Why it matters: Using the wrong operator causes unexpected matches or misses.

Expert Zone

1

Regex patterns in nginx are compiled once and reused, so complex patterns impact startup time but not per-request latency.

2

The order of regex location blocks matters; nginx stops at the first matching regex, so ordering can control priority.

3

Using anchors (^, $) in regex improves performance by limiting the search space and avoiding partial matches.

When NOT to use

Avoid regex matches when simple prefix or exact matches suffice, as regex is slower. For complex routing, consider using nginx's map directive or external routing logic for better maintainability and performance.

Production Patterns

In production, regex matches are often used for file extensions (e.g., matching .php or .jpg), API versioning in URLs, or conditional routing based on patterns. Experts carefully order regex blocks and combine them with caching and rewrite rules for efficient, maintainable configurations.

Connections

Regular Expressions (Regex)

Regex match operators in nginx directly use regex syntax and semantics.

Understanding general regex concepts helps write correct nginx regex patterns and avoid errors.

HTTP Request Routing

Regex matching is a method of routing HTTP requests based on URL patterns.

Knowing routing principles clarifies why and how regex matching controls request flow.

Compiler Optimization

nginx compiles regex patterns once to optimize runtime performance, similar to how compilers optimize code.

Recognizing this connection explains why config reloads are needed after regex changes.

Common Pitfalls

#1 Using ~ instead of ~* when case-insensitive match is needed.

Wrong approach:

location ~ ^/Images/ {
# expects to match /images/ but does not
}

Correct approach:

location ~* ^/Images/ {
# matches /Images/ and /images/
}

Root cause:

Confusing case-sensitive (~) and case-insensitive (~*) operators.

#2 Placing regex location blocks before prefix matches expecting prefix to take priority.

Wrong approach:

location ~ ^/api/ {
# regex block
}
location /api/ {
# prefix block
}

Correct approach:

location /api/ {
# prefix block
}
location ~ ^/api/ {
# regex block
}

Root cause:

Misunderstanding nginx's matching order: prefix matches are tested before regex.

#3 Writing regex without anchors causing unintended partial matches.

Wrong approach:

location ~ images {
# matches any URL containing 'images' anywhere
}

Correct approach:

location ~ ^/images/ {
# matches URLs starting with /images/
}

Root cause:

Not using ^ anchor to specify start of string in regex.

Key Takeaways

nginx uses ~ for case-sensitive and ~* for case-insensitive regex matching in location blocks.

Regex matching allows flexible URL routing but is slower than prefix or exact matches.

nginx tests exact and prefix matches before regex matches, which are tested in order.

Regex patterns are compiled once at startup and cached for performance.

Understanding regex anchors and matching order prevents common configuration errors.