Install OpenResty - Complete Setup Guide for All Platforms
OpenResty is a full web platform built on nginx and LuaJIT. It lets you build high-performance web applications, API gateways, and WAFs entirely in Lua — without sacrificing nginx’s throughput. Whether you are deploying a new edge node or migrating from stock nginx, you need a reliable way to install OpenResty on your operating system.
There are two paths. Package manager installation (recommended for production) gives you signed, tested binaries with automatic updates via apt, dnf, or apk. Building from source suits advanced users who need custom nginx modules, non-standard install prefixes, or platforms without pre-built packages.
This page is the hub for both approaches — an OpenResty installation guide covering every major Linux distribution, ARM64, Alpine, and macOS. Pick your platform below, or jump to the Quick Start if you are on Ubuntu or Debian. Once OpenResty is running, the OpenResty Tutorial → is the recommended next step — a seven-step hands-on series from Hello World to production Lua applications.
Supported Platforms
OpenResty provides official pre-built packages for the following platforms. All listed Linux distributions also support ARM64 / Aarch64 — use the architecture-specific repository URL noted in each guide.
| Platform | Versions | Status | Detailed Guide |
|---|---|---|---|
| Ubuntu | 18.04, 20.04, 22.04, 24.04 | ✅ Supported | Install OpenResty on Ubuntu → |
| Debian | 11, 12 | ✅ Supported | Install OpenResty on Debian → |
| CentOS / RHEL / Rocky / Alma / Oracle | CentOS/RHEL 7–9; Rocky/Alma 8–9; Oracle 7–8 | ✅ Supported | RHEL-family section below |
| ARM64 / Aarch64 | Cross-distro | ✅ Supported | ARM64 section below |
| Alpine Linux | 3.10 – 3.18 | ✅ Supported | Alpine section below |
| macOS (Homebrew) | Latest | ✅ Supported | macOS section below |
| Build from source | Any Linux / Unix | ✅ Supported | Source build section below |
For the full list of supported distributions — including Fedora, Amazon Linux, Rocky Linux, and SUSE — see the official Linux Packages page.
Quick Start
The fastest way to install OpenResty on Ubuntu or Debian (amd64) takes five commands. These steps work on Ubuntu 22.04+. Debian 12 follows the same steps, with different commands for Steps 2 and 3 (shown below). Ubuntu 18.04/20.04 and Debian 11 import the GPG key with apt-key instead — see the full Ubuntu guide and the Debian guide for those commands.
If nginx is already installed and running, disable and stop it first, otherwise the installation might fail:
sudo systemctl disable nginx
sudo systemctl stop nginx
Step 1 — Install prerequisites:
sudo apt-get -y install --no-install-recommends wget gnupg ca-certificates lsb-release
Step 2 — Import the OpenResty GPG key:
wget -O - https://openresty.org/package/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/openresty.gpg
Step 3 — Add the official APT repository:
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/openresty.gpg] https://openresty.org/package/ubuntu $(lsb_release -sc) main" \
| sudo tee /etc/apt/sources.list.d/openresty.list > /dev/null
On Debian 12, use these commands for Steps 2 and 3 instead:
wget -O - https://openresty.org/package/pubkey.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/openresty.gpg
codename=`grep -Po 'VERSION="[0-9]+ \(\K[^)]+' /etc/os-release`
echo "deb https://openresty.org/package/debian $codename openresty" \
| sudo tee /etc/apt/sources.list.d/openresty.list
For ARM64 systems, use arm64/ubuntu or arm64/debian in the repository URL instead — see the ARM64 section.
Step 4 — Update the package index and install:
sudo apt-get update
sudo apt-get -y install --no-install-recommends openresty
Step 5 — Start the service and verify:
sudo systemctl start openresty
curl 127.0.0.1/
You should see the default OpenResty welcome page. For a full walkthrough with screenshots and optional packages, see the complete Ubuntu installation guide →.
Platform Installation Guides
Ubuntu (20.04 / 22.04 / 24.04)
OpenResty provides official APT repositories for all current Ubuntu LTS releases on both amd64 and arm64. The installation process covers GPG key setup, repository configuration, package installation, and optional tools like resty, restydoc, and OPM.
Install OpenResty on Ubuntu — full step-by-step guide →
Debian (11 / 12)
Debian uses a dedicated APT repository separate from Ubuntu. The repo supports Bullseye (11) and Bookworm (12) on both x86_64 and aarch64 architectures. Debian 13 is not supported yet.
Install OpenResty on Debian — full step-by-step guide →
CentOS / RHEL / Rocky / Alma / Oracle
RHEL-family distributions share the same YUM/DNF repository model: put your distribution’s .repo file into /etc/yum.repos.d/, then install with dnf install openresty (use yum on version 7). The one thing that changes between versions is the repo file name — version 9 and later use openresty2.repo, while version 8 and earlier use openresty.repo. For example, on CentOS 9:
wget https://openresty.org/package/centos/openresty2.repo
sudo mv openresty2.repo /etc/yum.repos.d/openresty.repo
sudo dnf check-update
sudo dnf install -y openresty
On RHEL or Rocky Linux, replace centos in the URL with rhel or rocky. AlmaLinux can use the Rocky repository directly. Oracle Linux uses oracle/openresty.repo.
See official RPM package instructions →
For a CentOS 8-specific walkthrough with screenshots, see our legacy CentOS 8 guide.
ARM64 / Aarch64
OpenResty provides ARM64 packages for Ubuntu, Debian, and RPM-based distributions such as CentOS, RHEL, Rocky, and Fedora. On Ubuntu and Debian, switch to the ARM64-specific repository URL; on RPM-based distributions, the setup commands are the same as on amd64.
Ubuntu (ARM64)
After importing the GPG key (same as amd64), use the ARM64 repository:
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/openresty.gpg] https://openresty.org/package/arm64/ubuntu $(lsb_release -sc) main" \
| sudo tee /etc/apt/sources.list.d/openresty.list > /dev/null
sudo apt-get update
sudo apt-get -y install openresty
Debian (ARM64)
codename=$(grep -Po 'VERSION="[0-9]+ \(\K[^)]+' /etc/os-release)
echo "deb https://openresty.org/package/arm64/debian $codename openresty" \
| sudo tee /etc/apt/sources.list.d/openresty.list
sudo apt-get update
sudo apt-get -y install openresty
CentOS / RHEL / Rocky / Fedora (ARM64)
The official RPM repository setup commands do not differ by architecture, and there is no separate repository URL for aarch64. Follow the RHEL-family section above and run dnf install openresty as usual.
For Fedora specifically (the official repository supports Fedora 32 through 36):
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo https://openresty.org/package/fedora/openresty.repo
sudo dnf install -y openresty
See the official Linux Packages page for the complete list of ARM64-supported distributions.
Alpine Linux
Alpine uses apk instead of apt or dnf. First, enable Alpine’s community repository by uncommenting the community line in /etc/apk/repositories:
https://mirror.leaseweb.com/alpine/v3.18/community
Your mirror URL and version number may differ. Then add the OpenResty repository:
# Add the public key used to sign the repo
wget 'https://openresty.org/package/admin@openresty.com-5ea678a6.rsa.pub'
sudo mv 'admin@openresty.com-5ea678a6.rsa.pub' /etc/apk/keys/
# Add the repo (adjust MAJOR_VER to your Alpine version)
. /etc/os-release
MAJOR_VER=$(echo $VERSION_ID | sed 's/\.[0-9]\+$//')
echo "https://openresty.org/package/alpine/v$MAJOR_VER/main" \
| sudo tee -a /etc/apk/repositories
sudo apk update
sudo apk add openresty
Optional packages: openresty-resty (CLI REPL), openresty-opm (Lua module manager), and openresty-restydoc (documentation browser). See Linux Packages: Alpine for details.
macOS (Homebrew)
On macOS, the recommended way to install OpenResty is via Homebrew:
brew install openresty/brew/openresty
If you previously installed nginx from homebrew/nginx, run brew untap homebrew/nginx first. For full macOS installation and source-build instructions, see the official Installation page.
Building from Source
Building from source gives you full control over compile-time options — custom nginx modules, non-default prefixes, and platforms without pre-built packages. The basic steps are:
tar -xvf openresty-VERSION.tar.gz
cd openresty-VERSION/
./configure -j2 --with-pcre-jit --with-ipv6
make -j2
sudo make install
export PATH=/usr/local/openresty/bin:$PATH
Replace VERSION with the latest release number from the Download page. Use ./configure --help to see all available options, including --add-module=PATH for third-party nginx modules.
Install build prerequisites first:
- Debian / Ubuntu:
sudo apt-get install libpcre3-dev libssl-dev perl make build-essential curl - RHEL / Fedora:
sudo dnf install pcre-devel openssl-devel gcc curl zlib-devel
For the complete source build guide — including dependency management, configure options, and troubleshooting — see the official Installation documentation.
Verify Your Installation
After installing OpenResty on any platform, run these checks to confirm everything is working. This section applies to all distributions — child guides link back here instead of repeating the same steps.
Check the version
openresty -V
This prints the OpenResty version, nginx version, and enabled modules. You should see output starting with nginx version: openresty/ followed by the installed version number.
Start the default server
sudo systemctl start openresty # systemd-based distros
sudo openresty # Alpine or manual installs
Confirm nginx worker processes are running:
ps aux | grep nginx
Test the default home page
curl 127.0.0.1/
A successful response shows the OpenResty welcome page HTML.
Install optional tools
The resty command-line utility ships separately from the openresty package. On Debian/Ubuntu, openresty also pulls in openresty-opm and openresty-restydoc as recommended packages, unless you install it with --no-install-recommends (as in Quick Start). Install any missing tools from the same repository:
| Package | Command | Purpose |
|---|---|---|
openresty-resty | resty -e 'print("Hello")' | Lua REPL for quick scripting |
openresty-restydoc | restydoc -s content_by_lua_file | Browse nginx/OpenResty docs in the terminal |
openresty-opm | opm get pintsized/lua-resty-http | Install community Lua modules |
Example on Debian/Ubuntu:
sudo apt-get -y install openresty-resty openresty-restydoc openresty-opm
resty -e 'print("Hello Resty")'
On RHEL-family systems, use dnf install, and note that restydoc ships in the openresty-doc package there: sudo dnf install -y openresty-resty openresty-doc openresty-opm. On Alpine, use apk add openresty-resty openresty-opm openresty-restydoc.
Enable OpenResty at boot
sudo systemctl enable openresty
Upgrading OpenResty
To upgrade all installed OpenResty packages to the latest version:
Debian / Ubuntu:
sudo apt-get update
sudo apt-get --only-upgrade -y install 'openresty*'
RHEL / Rocky / Alma / CentOS:
sudo dnf check-update
sudo dnf upgrade 'openresty*'
Alpine:
sudo apk update
sudo apk upgrade openresty
FAQ
What is OpenResty used for?
OpenResty turns nginx into a programmable application server. Developers use it to build high-performance web APIs, reverse proxies, load balancers, WAFs, and CDN edge nodes — all scripted in Lua with LuaJIT’s near-native execution speed. Major companies including Cloudflare and Taobao rely on OpenResty at scale.
Is OpenResty the same as Nginx?
No. OpenResty bundles a patched nginx core with LuaJIT and dozens of Lua libraries (lua-nginx-module, ngx_lua, lua-resty-*). You get nginx’s event-driven architecture plus a full scripting runtime. The openresty command replaces nginx and is API-compatible with standard nginx configuration.
Which Linux distros does OpenResty support?
OpenResty provides official pre-built packages for Ubuntu, Debian, CentOS, RHEL, Rocky Linux, AlmaLinux (via the Rocky repository), Fedora, Amazon Linux, Alpine, OpenSUSE, SUSE Linux Enterprise, Oracle Linux, CBL-Mariner, and several China-specific distributions (Alibaba Cloud Linux, TencentOS). Both x86_64 and ARM64/aarch64 are supported on most of these. See the Linux Packages page for the full matrix. Pre-built packages for Windows are available on the Download page.
Why does OpenResty fail with “Illegal instruction” after installing the package?
The official binary packages for x86_64 require a CPU with SSE 4.2 support. On an older CPU without SSE 4.2, the binaries fail with an Illegal instruction error. In that case, build OpenResty from the source tarball on that machine instead — see Building from Source.
How do I upgrade OpenResty to the latest version?
Run your package manager’s update command scoped to OpenResty packages. On Debian/Ubuntu: sudo apt-get update && sudo apt-get --only-upgrade -y install 'openresty*'. On RHEL-family: sudo dnf upgrade 'openresty*'. On Alpine: sudo apk upgrade openresty. For source builds, download the latest tarball and re-run ./configure && make && sudo make install.
If you found this guide useful, subscribe to this blog and our YouTube channel for more OpenResty tutorials.
Related Guides
- Install OpenResty on Ubuntu via apt-get
- Official OpenResty Debian 11 package repo
- Install OpenResty on CentOS 8 via dnf
- Official Linux Packages (openresty.org)
- Installation from Source (openresty.org)
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.












