Skip to content

locations: Lua library implementing nginx style location uri matching


If you haven't set up RPM repository subscription, sign up. Then you can proceed with the following steps.

CentOS/RHEL 7 or Amazon Linux 2

yum -y install
yum -y install lua-resty-locations

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

yum -y install
yum -y install lua5.1-resty-locations

To use this Lua library with NGINX, ensure that nginx-module-lua is installed.

This document describes lua-resty-locations v0.2 released on Aug 31 2017.

Lua library implementing nginx style 'location' uri matching.

As nginx's location feature.
Supports longest prefix matching, regex matching, case insensitive regex matching and exact matches.

  • Exact matches are checked first, search returns on hit.
  • Prefix matches then checked and the longest match is remembered.
  • If prefix match has ^~ modifier search returns
  • Regexes are checked in order
  • If no regex match longest prefix is returned


init_by_lua_block {
        local locations = require("resty.locations")
        my_locs = locations:new()

        -- Prefix match
        local ok, err = my_locs:set("/foo", "/foo")

        -- exact match
        local ok, err = my_locs:set("/bar", "= /bar", "=")

        -- regex match
        local ok, err = my_locs:set("^/baz", "~ ^/baz", "~")

        -- case insensitive regex match
        local ok, err = my_locs:set("^/qux", "~* ^/qux", "~*")

        -- prefix match, no regex check
        local ok, err = my_locs:set("/bazfoo", "^~ /bazfoo", "^~")

server {
    listen 80 default_server;

    server_name locations;

    location / {
        content_by_lua_block {
            local val, err = my_locs:lookup(ngx.var.uri)
            if val then
                -- do something based on val
                ngx.say("Matched: ", val)
                if err then
                    ngx.log(ngx.ERR, err)



syntax: my_locations, err = locations:new(size?)

Creates a new instance of resty-locations with an optional initial size


syntax: ok, err = my_locations:set(key, value, modifier?)

Adds a new key with associated value and modifier, default is an empty string for prefix match.
Keys must be strings.
Returns false and an error message on failure.

Modifiers are as the nginx location feature. * ` (empty string) - Prefix match *=- Exact match *~- Regex match *~*- Case insensitive regex match *^~` - Prefix match, skip regexes


syntax: val, err = my_locations:lookup(uri)

Retrieves value for provided uri.
Returns nil and an error message on failure


You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-locations.