What is the real nginx location selection algorithm?

This happens because the actual algorithm for selecting a location in nginx differs from what's described in the documentation. Or, to be more specific, the official documentation does not explain the location selection process for nested locations, which is considerably more complex. So far, I haven't come across any English-language articles explaining how it truly works, so here is my attempt to clarify it.

Let's start with the configuration provided in the original question:

location / {
    return 200 "Location 1\n";
}
location ~ \.php$ {
    return 200 "Location 2\n";
}
location /tmp {
    return 200 "Location 3\n";
    location ~ \.php$ {
        return 200 "Location 3a\n";
    }
}

One can think the request /tmp/foo.php will be proceed with the location ~ \.php$ { ... } (marked as "Location 2") since the documentation explicitly says:

To find location matching a given request, nginx first checks locations defined using the prefix strings (prefix locations). Among them, the location with the longest matching prefix is selected and remembered. Then regular expressions are checked, in the order of their appearance in the configuration file. The search of regular expressions terminates on the first match, and the corresponding configuration is used.

Let's check it:

> curl http://127.0.0.1/tmp/foo.php
Location 3a

Unexpected, isn't it? What documentation doesn't say is that after identifying the longest matching prefix location, nginx begins a new search iteration over its nested locations, if any. This process continues recursively: at each step, the same matching rules are applied, and if a matching nested regex location is found, while no nested longest prefix location is matched, nginx stops further searching and uses that location for handling the request.

In our example, for the /tmp/foo.php request:

1. Nginx first identifies the longest matching prefix location, location /tmp { ... } (marked as "Location 3").
2. A new search iteration begins over its nested locations.
3. The nested location ~ \.php$ { ... } (marked as "Location 3a") matches and is used for handling the request.

Now, let's extend the configuration by adding a fourth location:

location /tmp/foo {
    return 200 "Location 4\n";
}

Testing the same request:

> curl http://127.0.0.1/tmp/foo.php
Location 2

What happened here?

1. In the first step, the longest matching prefix location is location /tmp/foo { ... }.
2. Since it has no nested locations, nginx evaluates regex locations at the same level.
3. The regex location location ~ \.php$ { ... } matches and is used for handling the request.

Other requests like /tmp/bar.php continue to be processed as before:

> curl http://127.0.0.1/tmp/bar.php
Location 3a

Next, let's modify the configuration again, moving the location /tmp/foo { ... } inside the location /tmp { ... }:

location / {
    return 200 "Location 1\n";
}
location ~ \.php$ {
    return 200 "Location 2\n";
}
location /tmp {
    return 200 "Location 3\n";
    location ~ \.php$ {
        return 200 "Location 3a\n";
    }
    location /tmp/foo {
        return 200 "Location 3b\n";
    }
}

Running some tests:

> curl http://127.0.0.1/tmp/foo.php
Location 3a
> curl http://127.0.0.1/tmp/foo.html
Location 3b

Nothing unexpected so far.

Now, let's examine the ^~ location directive modifier. According to documentation:

If the longest matching prefix location has the ^~ modifier then regular expressions are not checked.

Let's check it using the following configuration:

location / {
    return 200 "Location 1\n";
}
location ~ \.php$ {
    return 200 "Location 2\n";
}
location /tmp {
    return 200 "Location 3\n";
    location ~ \.php$ {
        return 200 "Location 3a\n";
    }
}
location ^~ /tmp/foo {
    return 200 "Location 4\n";
}

Running some tests:

> curl http://127.0.0.1/tmp/foo.php
Location 4
> curl http://127.0.0.1/tmp/foo.html
Location 4
> curl http://127.0.0.1/tmp/bar.php
Location 3a
> curl http://127.0.0.1/tmp/bar.html
Location 3

Seems that everything works as expected. The ^~ modifier on location ^~ /tmp/foo { ... } ensures that the same level regex locations, such as location ~ \.php$ { ... }, cannot overtake matching requests like /tmp/foo.php.

Now, here's something that may really surprise you. Let's modify our configuration, moving the location ^~ /tmp/foo { ... } inside the location /tmp { ... } again:

location / {
    return 200 "Location 1\n";
}
location ~ \.php$ {
    return 200 "Location 2\n";
}
location /tmp {
    return 200 "Location 3\n";
    location ~ \.php$ {
        return 200 "Location 3a\n";
    }
    location ^~ /tmp/foo {
        return 200 "Location 3b\n";
    }
}

Let's test the same /tmp/foo.php request. You're expecting the response will be Location 3b, right?

> curl http://127.0.0.1/tmp/foo.php
Location 2

Oops... Looks weird, didn't it? Well, this is probably the last aspect of the algorithm that needs to be explained. After identifying the longest matching prefix location at the most nested level (in our case, the location ^~ /tmp/foo { ... }, marked as "Location 3b"), if no matching regex locations are found within it, nginx remembers that location and begins ascending the configuration tree back up to the outermost level. On each level it passes during the ascent, the following actions are taken:

• If the longest matching prefix location on the current level doesn't have a ^~ modifier, nginx matches the request against all regex locations defined at that level. The first matching regex location, if any, is used to handle the request; otherwise, nginx continues ascending.
• If the longest matching prefix location on the current level has a ^~ modifier, nginx skips matching the request against regex locations defined on that level and immediately ascends to the next level up. If it has already reached the outermost level, the remembered longest matching prefix location from the most nested level is used to handle the request.

That's it. Having the ^~ modifier on a nested prefix location (location 3b) doesn't guarantee that the request will not be overtaken by an outer regex location (location 2) if the outermost longest matching prefix location (location 3) doesn't have ^~ modifier.

P.S. Of course, it should be mentioned that if an exact match location (a location with the = modifier) is found at any level during the descent, nginx immediately stops searching, and the found location is used to handle the request. Considering it, a typical nginx configuration like

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass unix:/path/to/php-fpm/socket;
}

can be significately optimized if the index.php file is the sole handler for the requests, which is common in many use cases:

location = /index.php {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass unix:/path/to/php-fpm/socket;
}