Install NGINX Lua Module on Rocky Linux, AlmaLinux, CentOS & RHEL

📅 Updated: January 28, 2026 (Originally published: March 27, 2020)

Lua is a lightweight scripting language that extends NGINX with powerful programmable logic. Combined with LuaJIT2’s blazing-fast execution, you can implement custom authentication, request routing, API gateways, and dynamic content generation directly in NGINX.

This guide shows you how to install the NGINX Lua module on RHEL-based systems using pre-built RPM packages from the GetPageSpeed repository.

Why Use Lua in NGINX?

The Lua module enables capabilities that aren’t possible with standard NGINX configuration:

• Custom authentication – Integrate with external services, implement JWT validation
• Request manipulation – Modify headers, rewrite URLs based on complex logic
• API gateways – Rate limiting, request routing, response transformation
• Dynamic content – Generate responses without a backend application
• Form protection – Integrate with anti-spam services like CleanTalk

Install NGINX Lua Module

Step 1. Add GetPageSpeed Repository

For Rocky Linux, AlmaLinux, CentOS 8/9, or Fedora:

sudo dnf -y install https://extras.getpagespeed.com/release-latest.rpm

For CentOS/RHEL 7 or Amazon Linux 2:

sudo yum -y install https://extras.getpagespeed.com/release-latest.rpm

Note: An active NGINX Extras subscription is required for RHEL-based systems. Fedora users have free access.

Step 2. Install the Lua Module

For Rocky Linux, AlmaLinux, CentOS 8/9, or Fedora:

sudo dnf install -y nginx nginx-module-lua

For CentOS/RHEL 7 or Amazon Linux 2:

sudo yum install -y nginx nginx-module-lua

Step 3. Enable the Module

Add these lines at the top of /etc/nginx/nginx.conf:

load_module modules/ndk_http_module.so;
load_module modules/ngx_http_lua_module.so;

Note: The NDK (Nginx Development Kit) module must be loaded first as Lua depends on it.

Step 4. Start or Reload NGINX

For new installations:

sudo systemctl enable --now nginx

For existing installations:

sudo systemctl reload nginx

Verify Lua Works

Add a test location to any server block:

server {
    location /lua_test {
        default_type 'text/plain';
        content_by_lua_block {
            ngx.say('Hello from Lua!')
        }
    }
}

Reload NGINX and visit /lua_test. You should see “Hello from Lua!”.

Common Use Cases

Simple Request Logging

location / {
    log_by_lua_block {
        ngx.log(ngx.INFO, "Request from: " .. ngx.var.remote_addr)
    }
}

Custom Header Based on Logic

location / {
    header_filter_by_lua_block {
        if ngx.var.request_uri:match("^/api/") then
            ngx.header["X-API-Version"] = "2.0"
        end
    }
}

Dynamic Response

location /time {
    default_type 'application/json';
    content_by_lua_block {
        ngx.say('{"timestamp": ' .. ngx.time() .. '}')
    }
}

Install Additional Lua Libraries

Many useful Lua libraries are available as RPM packages. Search for them:

For Rocky Linux, AlmaLinux, CentOS 8/9, or Fedora:

sudo dnf search lua-resty

For CentOS/RHEL 7:

sudo yum search lua-resty

Popular libraries include:
– lua-resty-http – HTTP client
– lua-resty-redis – Redis client
– lua-resty-mysql – MySQL client
– lua-resty-jwt – JWT handling

Real-World Examples

Protect Signup Forms from Spam

Use Lua to integrate with CleanTalk or other anti-spam services. See our guide on protecting signup forms with NGINX and CleanTalk.

Advanced Rate Limiting

While NGINX has built-in rate limiting, Lua enables more sophisticated rules:
– Rate limits based on authentication status
– Dynamic limits based on user behavior
– Graduated response (warn → delay → block)

Performance Notes

The GetPageSpeed Lua module uses OpenResty’s LuaJIT2 fork, which provides:
– JIT compilation – Lua code compiles to native machine code
– Low latency – Microsecond-level execution times
– Shared memory – Share data between worker processes via lua_shared_dict

Lua scripting adds minimal overhead when written correctly. Avoid blocking operations and use NGINX’s non-blocking APIs.