What Is OpenResty? From Nginx and LuaJIT to Real-World Use Cases

Check out how OpenResty XRay helps organizations troubleshoot issues and optimize the performance of their applications.

Learn More LIVE DEMO

OpenResty is an open-source web platform: it bundles an enhanced Nginx core, LuaJIT, and a set of Lua libraries into a single distribution, so you can write request-handling logic for Nginx directly in Lua. It is not a new server that stands apart from Nginx, but a platform built on top of it: OpenResty tracks official Nginx releases, the executable is still nginx, and your existing Nginx configuration keeps working. OpenResty is maintained by OpenResty Inc..

Nginx is already powerful on its own: static files, reverse proxying, load balancing, caching, and rate limiting are all available through configuration. The trouble starts when you need to handle requests by your own rules: authenticating users, say, or custom rate limiting and routing. Complex decisions are awkward to express in Nginx directives, many directives require repeated trips to the documentation to confirm how they behave, and long configurations quickly become hard to maintain. Writing a module in C is expensive, and you may have to recompile it every time you upgrade Nginx. Handing the work to an external service adds an extra network round trip to every request. OpenResty lets you write this logic in Lua right inside Nginx: the code stays well organized, and changing the logic does not require recompiling Nginx. Think of it this way: if Nginx is a fully featured calculator, OpenResty upgrades it into a programmable computer, taking you from configuring existing features to writing your own logic.

This post is written by the OpenResty maintainers. It walks through what OpenResty can do, how it works, what it is made of, and how open-source OpenResty relates to the associated commercial products.

What OpenResty Is Used For

OpenResty is typically used where a service sits in front of your backends and needs to inspect and act on every request:

• API gateways and open API platforms: handle authentication, signature verification, rate limiting, routing, and protocol conversion before requests reach the backend. SaaS products and paid APIs can also enforce per-customer quotas and record usage.
• Web application firewalls (WAF): inspect requests in Nginx’s access phase to block attacks such as SQL injection and XSS, and enforce access rules such as IP allowlists and blocklists.
• Dynamic routing, canary releases, and load balancing: decide in real time which upstream receives a request based on request headers, cookies, or configuration stored in Redis, and send a share of traffic to a new version by user or by percentage. Upstream changes do not require an Nginx reload (see the Redis-based dynamic routing example on openresty.org).
• Traffic protection for flash sales and peak shopping events: cache product pages and API responses, throttle request rates, and block abnormal requests during traffic peaks to protect backend services.
• CDNs and edge nodes: control caching, rewrite requests, and filter responses on nodes close to users.
• AI / LLM gateways: proxy requests to multiple models through one entry point, allocate traffic by team or application, and enforce token quotas.
• High-concurrency web services: build complete web applications or APIs directly in Nginx, with non-blocking access to MySQL, PostgreSQL, Redis, and Memcached.

What these scenarios have in common is that the logic has to run on the request path. Move it into a separate service outside Nginx, and every request pays for an extra network round trip, while the team has one more service to deploy and monitor. Update routes through frequent reloads, and you hurt response latency and reset load-balancing state. OpenResty puts the logic inside the Nginx process itself: requests no longer have to hop to a separate service, route updates need no reload, the team writes application logic in a scripting language, and deployment and operations still follow the familiar Nginx approach.

Once your node count grows to the point where configuration needs to be managed centrally, open-source OpenResty does not by itself provide a full management console or configuration distribution system. At that point you can adopt OpenResty Edge to manage load balancing, WAF, caching, and routing policies centrally and push configuration to many nodes, with versioning and rollback, while keeping your existing Lua scripts and OpenResty runtime.

How OpenResty Works

In short, OpenResty works like this:

1. Nginx handles networking and the event loop. Each worker process uses a single thread and serves thousands of connections concurrently through an event-driven model.
2. Lua code hooks into request-processing phases. Nginx splits the handling of a request into phases such as rewrite, access, content, and log, and the response passes through header/body filters before it goes out. ngx_lua, OpenResty’s core component, lets you insert Lua code at these points (rewrite_by_lua*, access_by_lua*, content_by_lua*, and so on). When a request needs to be forwarded upstream, balancer_by_lua* lets Lua logic pick the upstream node. Each request runs in its own Lua coroutine.
3. Backend access goes through cosockets and never blocks the thread. Cosockets are OpenResty’s non-blocking network API. When Lua code connects to Redis, MySQL, or an upstream HTTP service, the cosocket API suspends the current coroutine while it waits for data, freeing the worker to handle other requests, and resumes the coroutine once the data arrives. To the developer, the code reads like an ordinary synchronous call. Cosockets are available in the rewrite, access, and content phases, among others, and in timers (see the lua-nginx-module documentation for the full list of contexts), but not in the filter and log phases, which are meant for lightweight rewriting and logging.

Each worker process has its own LuaJIT virtual machine, and hot code is JIT-compiled to machine code. Data that workers need to share, such as counters and rate-limiting state, lives in lua_shared_dict shared memory zones.

Open-source OpenResty provides the runtime capabilities, but troubleshooting still usually depends on logs, metrics, and manual analysis. When you see CPU spikes, rising memory usage, or slow requests in production, you can use OpenResty XRay to dynamically trace running OpenResty, Nginx, and LuaJIT programs and pinpoint expensive code paths with flame graphs, without changing code or restarting the application. OpenResty XRay is a separate commercial diagnostic tool, not a required component for running OpenResty.

Do You Need to Know Lua?

Not to get started. The way you configure Nginx does not change, and you can add just a few lines of Lua to the one location that needs custom logic:

location /hello {
    default_type text/plain;
    content_by_lua_block {
        local name = ngx.var.arg_name or "world"
        ngx.say("hello, ", name)
    }
}

A request to /hello?name=openresty returns hello, openresty. Everything inside content_by_lua_block is Lua; everything outside it is still standard Nginx directives. OpenResty’s LuaJIT is fully compatible with Lua 5.1, and Lua’s syntax is concise, so the learning curve is gentle.

To try it yourself, start by installing OpenResty, then follow the seven steps of the OpenResty Tutorial from Hello World to production.

Is OpenResty a Web Server? How Does It Relate to Nginx?

Yes. OpenResty is a complete web server in its own right, and it can also act as a reverse proxy, load balancer, and TCP/UDP proxy. When you start OpenResty, what actually runs is an Nginx process; the openresty command is usually just a launcher for the bundled nginx executable.

Its relationship to standard Nginx shows up right in the version number: the first three parts of an OpenResty version number are the version of the Nginx core it bundles. For example, OpenResty 1.31.1.1 bundles Nginx 1.31.1, and the fourth part is OpenResty’s own revision number. If you see openresty/1.31.1.1 in a website’s response headers or on an error page, that’s the OpenResty version the server is running.

According to the openresty.org FAQ, OpenResty follows a “tick-tock” release model: a tock release upgrades the Nginx core to the latest official mainline version, and the tick release that follows focuses on OpenResty’s own features and improvements. Changes in each release are listed in the release announcements on openresty.org, such as the OpenResty 1.31.1.1 release announcement.

What OpenResty Is Made Of

According to openresty.org, most of the Nginx modules in OpenResty are developed by its maintainers, which is why they work well together. The main components are:

See the component list on openresty.org for the full inventory. If the open-source libraries fall short on performance or features for a particular use case, you can use the OpenResty private libraries from OpenResty Inc. to replace or enhance some Lua libraries and Nginx modules. Many more community-contributed Lua libraries are available on OPM.

Who Uses OpenResty

According to Netcraft’s July 2026 Web Server Survey, about 120 million websites (8.02% of all sites counted by Netcraft) and about 42.7 million domains (13.98%) run OpenResty, ranking it fourth among web servers worldwide on both measures.

Beyond direct deployments, OpenResty is also the runtime underneath many infrastructure products, including several widely used open-source API gateways. So even a company that has never installed OpenResty itself may still have its request traffic passing through OpenResty.

Who Maintains OpenResty

OpenResty was created by Yichun Zhang (GitHub handle: agentzh) and is now maintained by OpenResty Inc., which supports the project together with the OpenResty Software Foundation.

OpenResty is free, open-source software, and most of the bundled components use permissive licenses such as BSD and MIT. Source code, prebuilt packages, and documentation are all available at openresty.org, with package repositories covering major Linux distributions including Ubuntu, Debian, the RHEL family, and Alpine.

OpenResty Inc. also offers separate commercial products (OpenResty Edge, OpenResty XRay, and the OpenResty private libraries) that add centralized multi-node management, production troubleshooting, and performance optimization for specific components, respectively. None of them is a prerequisite for running open-source OpenResty.

FAQ

What is the difference between OpenResty and Nginx?

OpenResty includes the full Nginx core and adds LuaJIT and Lua libraries on top. Standard Nginx configuration keeps working, and you can add Lua logic one location at a time as needed. In standard Nginx, anything that needs real programming usually means writing a C module or using another extension mechanism; OpenResty lets you do much of that in Lua.

Is OpenResty free to use?

Yes. OpenResty is open-source software, and using it in production requires no paid license. OpenResty Edge, OpenResty XRay, and the OpenResty private libraries from OpenResty Inc. are separate commercial products.

What software is built on OpenResty?

The open-source API gateways Kong and Apache APISIX both state in their official documentation that they run on OpenResty (Nginx + LuaJIT). OpenResty Edge from OpenResty Inc. is also built on OpenResty.

Which version of Lua does OpenResty use?

OpenResty ships its own maintained branch of LuaJIT 2.1, which is fully compatible with Lua 5.1 and supports some Lua 5.2 and Lua 5.3 extensions. Standard Lua 5.1 code runs unmodified, and LuaJIT-specific features such as the FFI are available too. For network access, use the non-blocking APIs provided by ngx.* and the lua-resty-* libraries, so the worker can keep handling other requests while it waits for data.

What does “403 Forbidden openresty” on a web page mean?

It means the website’s server runs OpenResty; the openresty or openresty/1.31.1.1 at the bottom of the error page is the server name and version. Status codes such as 403, 404, 502, and 504 are determined by that website’s own configuration or its backend services, and do not mean the OpenResty software itself has failed. If you are a visitor, contact the site owner. If you are the site administrator, start with Nginx’s error.log to find out why the request was denied or why the upstream failed.

How do I troubleshoot an OpenResty application?

Lua runtime errors are written to Nginx’s error.log, which is the first place to look; the resty command-line tool is handy for reproducing problems outside the server. CPU spikes, rising memory usage, or slow requests in production often cannot be pinned down from logs alone. In those cases, you can use OpenResty XRay to generate Lua-level CPU flame graphs for running processes and see the expensive code paths directly.

Next Steps

• Install OpenResty: installation guides for each Linux distribution, ARM64, macOS, and building from source
• OpenResty Tutorial: a seven-step hands-on series from Hello World to production
• OpenResty Documentation and Getting Started: the getting-started guide on openresty.org
• OpenResty Release Announcement: what changed in the latest release

About The Author

Yichun Zhang (GitHub handle: agentzh), is the original creator of the OpenResty^® open-source project and the CEO of OpenResty Inc..

Yichun is one of the earliest advocates and leaders of “open-source technology”. He worked at many internationally renowned tech companies, such as Cloudflare, Yahoo!. He is a pioneer of “edge computing”, “dynamic tracing” and “machine coding”, with over 22 years of programming and 16 years of open source experience. Yichun is well-known in the open-source space as the project leader of OpenResty^®, adopted by more than 40 million global website domains.

OpenResty Inc., the enterprise software start-up founded by Yichun in 2017, has customers from some of the biggest companies in the world. Its flagship product, OpenResty XRay, is a non-invasive profiling and troubleshooting tool that significantly enhances and utilizes dynamic tracing technology. And its OpenResty Edge product is a powerful distributed traffic management and private CDN software product.

As an avid open-source contributor, Yichun has contributed more than a million lines of code to numerous open-source projects, including Linux kernel, Nginx, LuaJIT, GDB, SystemTap, LLVM, Perl, etc. He has also authored more than 60 open-source software libraries.