Master OpenResty Package Management with OPM: A Complete Guide

Overview

OpenResty is a web platform built on Nginx that bundles many Nginx modules and Lua libraries. It provides two package managers: OPM (the official OpenResty Package Manager) and LuaRocks (a generic Lua module manager).

OPM

OPM installs community‑contributed Lua modules from the central OPM repository, guaranteeing compatibility with OpenResty and preserving the non‑blocking event model.

Common commands

# opm --help
opm [options] command package...

Options:
  -h, --help          Print this help.
  --install-dir=PATH Install into the specified PATH instead of the system‑wide OpenResty tree.
  --cwd               Install into ./resty_modules/ under the current working directory.

Commands:
  build      Build a package tarball from the current directory.
  clean      Clean temporary files (e.g., "dist").
  info       Show detailed information about a package.
  get        Fetch and install a package (e.g., "openresty/lua-resty-lock").
  list       List all installed packages.
  remove     Uninstall a package.
  search     Search the server for packages matching a query.
  server-build Build a final package tarball for distribution.
  update     Update all installed packages to the latest versions.
  upgrade    Upgrade specific packages to the latest version.
  upload     Upload a package tarball (automatically runs build first).

Typical workflow

Search for a package

# opm search lua-resty-http
agentzh/lua-resty-http    Lua HTTP client cosocket driver for OpenResty/ngx_lua

Install a package

# opm get ledgetech/lua-resty-http
* Fetching ledgetech/lua-resty-http
  Downloading https://opm.openresty.org/api/pkg/tarball/ledgetech/lua-resty-http-0.17.1.opm.tar.gz
Package ledgetech/lua-resty-http 0.17.1 installed successfully under /usr/local/openresty/site/.

Show package details

# opm info lua-resty-http
Name       : lua-resty-http
Version    : 0.17.1
Abstract   : Lua HTTP client cosocket driver for OpenResty/ngx_lua
Author     : James Hurst
Account    : ledgetech
Code Repo  : https://github.com/ledgetech/lua-resty-http
License    : BSD 2‑Clause "Simplified" or "FreeBSD" license
Original Work : yes

List installed packages

# opm list
agentzh/lua-resty-http                     0.09

Upgrade a package

# opm upgrade lua-resty-http
* Fetching agentzh/lua-resty-http > 0.09
Package agentzh/lua-resty-http 0.09 is already the latest version.

Remove a package

# opm remove lua-resty-http
Package agentzh/lua-resty-http 0.09 removed successfully.

Location of installed modules

cd /usr/local/openresty/site/lualib/resty
ls
http.lua  http_headers.lua

Using lua-resty-http

The library provides a simple HTTP client for Lua code running under OpenResty.

Nginx configuration (example)

server {
    listen 80;
    server_name openresty.example.com;

    location /lua_http_test {
        default_type "text/html";
        lua_code_cache off;
        content_by_lua_file conf/lua/lua_http_test.lua;
    }
}

Lua script (conf/lua/lua_http_test.lua)

local httpc = require("resty.http").new()

-- Single‑shot request using the request_uri API
local res, err = httpc:request_uri("https://www.workerman.net/u/Tinywan", {
    method = "GET",
    body = "name=Tinywan&age=24",
    headers = { ["Content-Type"] = "application/x-www-form-urlencoded" },
    ssl_verify = false,
})

if not res then
    ngx.log(ngx.ERR, "request failed: ", err)
    return
end

ngx.say(res.body)

Test the endpoint with curl:

$ curl -i http://openresty.example.com/lua_http_test
HTTP/1.1 200 OK
Server: openresty/1.17.8.2
... (response body) ...

LuaRocks

LuaRocks is a generic Lua module manager. While it can install Lua libraries, modules installed via LuaRocks may perform blocking I/O and therefore can degrade OpenResty’s event‑driven performance. For OpenResty projects, OPM is the recommended tool.