OpenResty Components: Modules, Lua Libraries, and How to Check Them
OpenResty’s core components are the NGINX core, which receives requests and manages connections; ngx_lua, which runs Lua code at different request phases; LuaJIT, which executes that Lua code; and Lua libraries such as lua-resty-redis, which your code calls to reach services like Redis. Command-line tools such as resty, restydoc, and opm are usually installed from separate optional packages.
This article introduces the common building blocks in OpenResty and shows how to check whether they are available in your environment. For the platform’s overall positioning and use cases, see What Is OpenResty.
How the core components work together
Consider a Redis lookup. NGINX receives the request and manages connections; ngx_lua lets you insert Lua code at different request phases; LuaJIT runs that code; and the code calls lua-resty-redis when it needs Redis.
One common source of confusion for new OpenResty users is the difference between an NGINX module and a Lua library.
In short, an NGINX module extends the server itself; a Lua library is called by your Lua code. ngx_lua is an NGINX module that provides the entry point for Lua in configuration and the ngx.* API. lua-resty-redis is a Lua library that you load with require "resty.redis" to communicate with Redis.
Another behind-the-scenes component is lua-resty-core. It reimplements many ngx.* interfaces using LuaJIT FFI. You may rarely call it directly, but it is an important foundation for OpenResty’s performance.
LuaJIT can also run ordinary Lua scripts from the luajit command. But code that uses the ngx.* API must run in an environment provided by OpenResty. To learn about the engine, see LuaJIT in OpenResty.
Common modules and libraries
Here are three categories of components you will encounter most often.
Server modules
ngx_lua(lua-nginx-module): The core module for running Lua during HTTP request processing and exposing thengx.*API.ngx_stream_lua(stream-lua-nginx-module): Similar tongx_lua, but for TCP/UDP Layer 4 traffic.headers-more(headers-more-nginx-module): Adds NGINX directives for conveniently adding, changing, or clearing HTTP request and response headers.
Depending on module support, NGINX modules can be statically compiled into the server or built as dynamic modules and loaded from the configuration.
Lua libraries
- lua-resty-core: A core library that implements some
ngx.*interfaces using LuaJIT FFI. - lua-resty-redis and lua-resty-mysql: Nonblocking Redis and MySQL clients, often used to look up accounts, configuration, or business state.
- lua-cjson: Converts Lua tables to and from JSON efficiently.
- lua-resty-lrucache and lua-resty-lock: The former provides per-worker LRU caching; the latter provides nonblocking locks based on shared-memory dictionaries, often to prevent cache stampedes.
- lua-resty-limit-traffic: Controls request rates and concurrent connections for gateway rate limiting.
- lua-resty-websocket: Implements WebSocket server or client communication in Lua.
- lua-resty-upstream-healthcheck: Actively checks NGINX upstream server health and removes unhealthy nodes, with the required modules and configuration.
These are only a few examples. See the official OpenResty component list for the full list. Not every listed component is included in every installation package, and some require extra configuration. Check your environment before coding.
Command-line tools
OpenResty also provides handy command-line tools, usually in separate optional packages:
resty: Runs OpenResty Lua scripts from the terminal, useful for small tests and debugging.restydoc: Reads the locally installed reference documentation from the terminal.opm: The official package manager for installing and managing community Lua packages.
Where OpenResty components are installed: lualib and site/lualib
Where are the components installed? As an example, consider the official DEB package 1.31.8.1-1~noble1 for Ubuntu 24.04 ARM64 (see the official package directory). If the main openresty package and the openresty-resty, openresty-restydoc, and openresty-opm utility packages are installed, /usr/local/openresty/ has a structure similar to this:
/usr/local/openresty/
├── bin/ # openresty, resty, restydoc, opm commands
├── nginx/
│ ├── conf/nginx.conf # default server configuration
│ └── sbin/nginx # server binary
├── luajit/ # LuaJIT command and runtime libraries
├── lualib/
│ └── resty/
│ ├── core.lua
│ └── redis.lua # Redis client included in the distribution
├── pod/ # restydoc documentation data
└── site/
└── lualib/ # system-wide OPM Lua library installation
Pay special attention to the two Lua library directories:
lualib/contains Lua libraries included in the official OpenResty distribution, such as theredis.luamentioned earlier.site/lualib/contains third-party community libraries installed globally withopm. Usingopm --cwdinstalls them in the current project instead.
If require reports that a library cannot be found, check these directories and confirm that lua_package_path in nginx.conf includes the library’s location. See the OPM documentation and the OpenResty Lua module tutorial for more.
How to check which components your OpenResty includes
During development and operations, you may find that a documented feature is unavailable in your environment. Different component types require different checks:
| What to check | How | Notes and limitations |
|---|---|---|
| Which executable the terminal uses | command -v openresty, openresty -V | The terminal executable may not be the instance running in production. |
| Whether a C module was compiled in | Check -V output for the target binary | A dynamic module may be built but not loaded by the configuration. |
| Whether a dynamic module is loaded | Run -T with the target binary and configuration parameters; inspect load_module | The result applies only to the configuration you checked. |
| Whether a Lua library loads | Run require in the relevant runtime context | Loading successfully does not prove that an external service is reachable. |
| Why a utility command is missing | Check package installation and PATH | Missing CLI tools do not prevent the server from handling traffic. |
Check the binary and build options with openresty -V
First determine which program runs when you type openresty, and which modules were compiled into it:
command -v openresty
readlink -f "$(command -v openresty)"
openresty -V
In our Ubuntu example, /usr/bin/openresty is a symbolic link to /usr/local/openresty/nginx/sbin/nginx. Running openresty -V prints output similar to this (split across lines for readability):
nginx version: openresty/1.31.8.1
--prefix=/usr/local/openresty/nginx
--add-module=../ngx_lua-0.10.32rc7
--add-module=../ngx_stream_lua-0.0.20rc3
--prefixis the default working-directory prefix set at build time; startup can override it with-p.--add-modulemeans the module was statically compiled into the server binary and is ready to use.--add-dynamic-modulemeans it was built as a dynamic module; check whether the configuration loads it withload_module.
For details, see NGINX command-line switches and NGINX configure options.
A common production pitfall is having multiple NGINX or OpenResty installations. The command in your terminal may not be the service running in the background. If systemd manages the service, use systemctl show -p ExecStart openresty to find its actual binary path and startup arguments (-p, -c, -g, and so on). Then export the configuration with -T using the same binary and arguments, and search it for load_module.
Verify that a Lua library loads
The included lua-resty-redis is installed with the main package. If the resty command-line tool is also installed, verify it from the terminal:
resty -e 'require "resty.redis"; print("resty.redis loaded")'
If it prints resty.redis loaded, the library file is present and can be loaded. If resty is not found, check the utility package and PATH. If the error says module not found, check the lualib directory and Lua search path. This only checks loading in resty’s default environment; it does not connect to Redis. If your gateway overrides lua_package_path, verify it in the actual service too.
Find missing command-line tools
The server may be working normally while restydoc or opm returns command not found. These tools are often split into optional packages:
| Command | Purpose | Debian / Ubuntu and Alpine | RPM systems (RHEL / CentOS, etc.) |
|---|---|---|---|
openresty | Start the server or check configuration | openresty | openresty |
resty | Run OpenResty Lua scripts in the terminal | openresty-resty | openresty-resty |
restydoc | Read local offline documentation | openresty-restydoc | openresty-doc |
opm | Install and manage community Lua packages | openresty-opm | openresty-opm |
On Ubuntu, APT usually installs the recommended openresty-resty and openresty-opm packages along with the main package, but openresty-restydoc may need to be installed manually. If a command is missing, use dpkg -s openresty-restydoc to check whether it is installed and dpkg -L openresty-restydoc to see where its files are installed and whether they are on your PATH. See the official DEB, RPM, and Alpine package notes for platform-specific details.
One special case: the well-known community test framework Test::Nginx is an independent Perl module, not installed under /usr/local/openresty/. A later article in this tutorial series uses it to test a small gateway.
Frequently asked questions
Can I remove modules or tools I do not use?
It depends on the component:
- Static modules: They are part of the server binary. If binary size or security requirements mean they must be removed, rebuild OpenResty without the corresponding
--add-moduleoption. - Dynamic modules: First confirm that neither the application configuration nor other modules depend on them. Remove the related directives and
load_moduleline, then test the configuration with the target binary and-t. - Command-line tools: Uninstall optional packages such as
restydocoropmwith the system package manager (apt,yum, etc.), and review dependency notices.
What is the difference between an NGINX module and a Lua library?
An NGINX module extends the server itself; a Lua library is called by your Lua code. ngx_lua is an NGINX module that provides the entry point for Lua in configuration and the ngx.* API. lua-resty-redis is a Lua library that you load with require "resty.redis" to communicate with Redis. NGINX modules are either statically compiled into the server or built as dynamic modules and loaded from the configuration.
Why does require say a Lua library cannot be found?
Check the two library directories under the installation prefix: lualib/ holds libraries included in the official distribution, and site/lualib/ holds community libraries installed globally with opm. Then confirm that lua_package_path in nginx.conf includes the library’s location. If your gateway overrides lua_package_path, verify loading in the actual service, not only with resty.
Why is restydoc or opm “command not found”?
These tools usually ship in separate optional packages, so the server can work normally while a command is missing. On Ubuntu, APT usually installs openresty-resty and openresty-opm with the main package, but openresty-restydoc may need to be installed manually; on RPM systems the documentation package is openresty-doc. Use dpkg -s to check whether a package is installed and dpkg -L to see where its files are and whether they are on your PATH.
Summary and next steps
When you are new to OpenResty, you do not need to memorize every component name. Start with this core model: NGINX handles networking and proxying, ngx_lua connects Lua to the request flow, and LuaJIT runs the code. When you need a database, cache, or rate limiter, find the relevant lua-resty-* library. If a module or library fails to load, first make sure you are checking the right instance, then inspect build options, library paths, or utility packages.
This article is part of the OpenResty tutorial series. Now that you know what OpenResty ships with, the next step is “Getting Started with Lua Scripting in NGINX,” where you will get hands-on with writing Lua code directly in an NGINX configuration file.
If you like this tutorial series, subscribe to this blog and our YouTube channel.
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.












