Skip to content

Installing & Compiling NGINX

This guide covers installing NGINX from packages (recommended) and building from source when needed.

For most users, installing pre-built packages is faster and easier to maintain.

Using NGINX Extras Repository

NGINX Extras provides NGINX with 100+ pre-built modules.

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

# Install with recommended modules (PageSpeed, Brotli, ModSecurity)
sudo dnf -y groupinstall "nginx extras recommended"

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

See APT NGINX Extras setup for instructions.

Installing Modules

# List available modules
sudo dnf list available | grep nginx-module

# Install a specific module
sudo dnf -y install nginx-module-brotli

# Enable in nginx.conf
load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_brotli_static_module.so;

Upgrading

# Update packages
sudo dnf upgrade nginx nginx-module-*

# Apply without downtime
sudo service nginx upgrade

Building from Source

Compile NGINX when you need custom patches or modules not available as packages.

Prerequisites

Build Tools

apt update
apt install build-essential git

yum groupinstall "Development Tools"
yum install git

xcode-select --install
brew install git

Dependencies

apt install libpcre3-dev zlib1g-dev libssl-dev \
            libgeoip-dev libxslt1-dev libgd-dev

yum install pcre-devel zlib-devel openssl-devel \
            geoip-devel libxslt-devel gd-devel

brew install pcre zlib openssl libgeoip libxslt gd

Download NGINX Source

# Download latest stable
wget https://nginx.org/download/nginx-1.24.0.tar.gz
tar -xzf nginx-1.24.0.tar.gz
cd nginx-1.24.0

# Or clone from repository
git clone https://github.com/nginx/nginx.git
cd nginx

Basic Build

Minimal Build

./configure
make
sudo make install

Default install location: /usr/local/nginx

Production Build

./configure \
    --prefix=/etc/nginx \
    --sbin-path=/usr/sbin/nginx \
    --conf-path=/etc/nginx/nginx.conf \
    --error-log-path=/var/log/nginx/error.log \
    --http-log-path=/var/log/nginx/access.log \
    --pid-path=/var/run/nginx.pid \
    --lock-path=/var/run/nginx.lock \
    --with-http_ssl_module \
    --with-http_v2_module \
    --with-http_realip_module \
    --with-http_gzip_static_module \
    --with-http_stub_status_module \
    --with-threads \
    --with-file-aio

make -j$(nproc)
sudo make install

Adding Modules

Static Modules (Compiled In)

./configure --add-module=/path/to/my_module

# Multiple modules
./configure \
    --add-module=/path/to/module1 \
    --add-module=/path/to/module2

Dynamic Modules (Loadable)

./configure --add-dynamic-module=/path/to/my_module

make modules

Output: objs/ngx_http_mymodule_module.so

Load in nginx.conf:

load_module modules/ngx_http_mymodule_module.so;

Module File Structure

Minimal Structure

my_module/
├── config              # Build configuration
└── ngx_http_mymodule.c # Source code

config File (Legacy)

# config
ngx_addon_name=ngx_http_mymodule_module

# For HTTP modules
HTTP_MODULES="$HTTP_MODULES ngx_http_mymodule_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_mymodule.c"

# For Stream modules
# STREAM_MODULES="$STREAM_MODULES ngx_stream_mymodule_module"

# Additional dependencies
NGX_ADDON_DEPS="$NGX_ADDON_DEPS $ngx_addon_dir/ngx_http_mymodule.h"

# Libraries
CORE_LIBS="$CORE_LIBS -lmylib"

config File (Modern - NGINX 1.9.11+)

# config
ngx_addon_name=ngx_http_mymodule_module
ngx_module_type=HTTP
ngx_module_name=ngx_http_mymodule_module
ngx_module_srcs="$ngx_addon_dir/ngx_http_mymodule.c"

# Optional
ngx_module_deps="$ngx_addon_dir/ngx_http_mymodule.h"
ngx_module_libs="-lmylib"
ngx_module_order="ngx_http_mymodule_module \
                  ngx_http_copy_filter_module"

. auto/module

Debug Build

Enable Debug Symbols

./configure \
    --with-debug \
    --with-cc-opt="-O0 -g -DNGX_DEBUG_MALLOC"

make

Debug Logging

error_log /var/log/nginx/debug.log debug;

events {
    debug_connection 127.0.0.1;
}

Core Dumps

# Set core dump size
ulimit -c unlimited

# Configure core dump location (Linux)
echo "/tmp/nginx-core.%p" > /proc/sys/kernel/core_pattern

# Enable in NGINX
working_directory /tmp;
worker_rlimit_core 500M;

Build Options Reference

Path Options

Option Description
--prefix=PATH Installation prefix
--sbin-path=PATH nginx binary path
--conf-path=PATH Config file path
--error-log-path=PATH Error log path
--pid-path=PATH PID file path
--lock-path=PATH Lock file path
--modules-path=PATH Dynamic modules path

HTTP Modules

Option Description
--with-http_ssl_module HTTPS support
--with-http_v2_module HTTP/2 support
--with-http_realip_module Real IP from proxy headers
--with-http_gzip_static_module Pre-compressed files
--with-http_auth_request_module Auth subrequests
--with-http_stub_status_module Status page
--with-http_sub_module Response substitution

Performance Options

Option Description
--with-threads Thread pool support
--with-file-aio Async file I/O (Linux)
--with-http_slice_module Range request caching

Compiler Options

Option Description
--with-cc=PATH C compiler path
--with-cc-opt=OPTIONS Additional compiler flags
--with-ld-opt=OPTIONS Additional linker flags
--with-cpu-opt=CPU CPU optimization

Building Third-Party Modules

Use Pre-Built Modules

Most popular modules are available as packages from NGINX Extras. This saves compilation time and ensures compatibility.

# Instead of compiling headers-more:
sudo dnf -y install nginx-module-headers-more

Example: Headers More Module (Manual Build)

# Download module
git clone https://github.com/openresty/headers-more-nginx-module.git

# Build with NGINX
cd nginx-1.24.0
./configure --add-module=../headers-more-nginx-module
make
sudo make install

Example: Dynamic Module

./configure \
    --add-dynamic-module=../headers-more-nginx-module \
    --with-compat

make modules

sudo cp objs/ngx_http_headers_more_filter_module.so /etc/nginx/modules/

Cross-Compilation

For embedded systems or different architectures:

./configure \
    --crossbuild=Linux:arm \
    --with-cc=arm-linux-gnueabihf-gcc \
    --with-cpp=arm-linux-gnueabihf-cpp \
    --with-cc-opt="-march=armv7-a" \
    --without-http_rewrite_module \
    --without-http_gzip_module

Troubleshooting

Common Errors

PCRE library not found: 

apt install libpcre3-dev  # Debian/Ubuntu
yum install pcre-devel    # RHEL/CentOS

OpenSSL not found: 

./configure --with-openssl=/path/to/openssl
# Or install system package
apt install libssl-dev

Module compatibility: 

# Check NGINX version in module
nginx -V 2>&1 | grep "nginx version"

# Rebuild module for current NGINX
./configure --add-dynamic-module=/path/to/module --with-compat

Checking Build Configuration

# Show compile options of installed NGINX
nginx -V

# Sample output:
# nginx version: nginx/1.24.0
# built with OpenSSL 1.1.1
# configure arguments: --with-http_ssl_module --with-http_v2_module ...

Makefile Targets

make                # Build nginx binary
make modules        # Build dynamic modules only
make install        # Install to prefix
make upgrade        # Hot upgrade binary

# Clean build
make clean

Development Workflow

Incremental Build

# Initial build
./configure --add-module=/path/to/mymodule --with-debug
make

# After source changes
make

# Test
objs/nginx -t -c /path/to/test.conf

Quick Test Setup

# Create minimal test config
cat > /tmp/nginx.conf << 'EOF'
daemon off;
master_process off;
error_log stderr debug;
events { }
http {
    server {
        listen 8080;
        location /test {
            my_directive;
        }
    }
}
EOF

# Run
objs/nginx -c /tmp/nginx.conf

Next Steps