Getting started

This page walks through the minimum needed to build nginx from this repository, run it, and run the test suite.

Prerequisites

Requirement	Why	Install (Debian/Ubuntu)
C compiler	nginx is C99 with GCC/Clang extensions	sudo apt install gcc make
PCRE2 (or PCRE) headers	rewrite + map directives use regular expressions	sudo apt install libpcre2-dev
zlib headers	gzip/gunzip filter modules	sudo apt install zlib1g-dev
OpenSSL 1.1.1+ headers	TLS, QUIC, HTTP/3	sudo apt install libssl-dev

The bundled modules http_xslt_filter, http_image_filter, http_geoip, and the Perl module each pull in their own optional libraries (libxslt, libgd, libgeoip, Perl). They are off by default; pass --with-http_xslt_module etc. to enable them.

Build

From the repo root:

auto/configure --with-debug --with-http_ssl_module --with-http_v2_module --with-http_v3_module
make -j$(nproc)

auto/configure prints a summary of which features were enabled, where binaries will be installed, and which compiler flags it selected. The result is a Makefile and ngx_auto_config.h under objs/. After make, the binary is at objs/nginx.

Useful configure flags:

Flag	Effect
--with-debug	Enable error_log debug; and ngx_log_debug* macros
--with-cc-opt='-O0 -g'	Override compiler flags (handy for debug builds)
--with-http_ssl_module	Enable ngx_http_ssl_module (TLS for HTTP)
--with-http_v2_module	Enable HTTP/2
--with-http_v3_module	Enable HTTP/3 over QUIC
--with-stream	Enable the generic TCP/UDP proxy (stream block)
--with-mail	Enable the mail proxy modules
--with-threads	Enable the thread pool (aio threads)
--add-module=/path/to/third/party	Statically build a third-party module
--add-dynamic-module=...	Build it as a .so loaded via load_module at runtime
--prefix=/usr/local/nginx	Install prefix (default /usr/local/nginx)

A complete reference is at nginx.org/en/docs/configure.html. The flags themselves are defined in auto/options.

Run

# from the repo root after building
./objs/nginx -p $PWD -c conf/nginx.conf -g 'daemon off;'

-p sets a prefix (so paths like logs/ resolve under the repo), -c selects a config file, and -g 'daemon off;' keeps the master in the foreground (useful under a debugger or strace). Hit localhost:80 and you should see the bundled "Welcome to nginx!" page.

Other useful invocations:

Command	Effect
nginx -t	Test the config without starting
nginx -T	Dump the parsed config (including all included files)
nginx -V	Print version + the configure args used at build time
nginx -s reload	Send SIGHUP (graceful reconfigure)
nginx -s reopen	Send SIGUSR1 (reopen log files for log rotation)
nginx -s quit	Send SIGQUIT (graceful shutdown)
nginx -s stop	Send SIGTERM (immediate stop)

CLI parsing lives in ngx_get_options() in src/core/nginx.c.

Test

The test suite is not in this repo. It lives in a sibling repository, nginx-tests:

git clone https://github.com/nginx/nginx-tests.git
cd nginx-tests
TEST_NGINX_BINARY=/path/to/objs/nginx prove -j8 .

Tests are written in Perl using a custom harness. Each .t file starts an isolated nginx instance with a generated config and exercises it with LWP::UserAgent, raw sockets, or IO::Socket::SSL. See how-to-contribute/testing for the conventions, environment variables, and how to run a single test.

Install (optional)

sudo make install

By default this puts files under /usr/local/nginx/:

Path	Purpose
/usr/local/nginx/sbin/nginx	The binary
/usr/local/nginx/conf/	nginx.conf, mime.types, FastCGI params
/usr/local/nginx/logs/	access.log, error.log, nginx.pid
/usr/local/nginx/html/	index.html, 50x.html

Override with --prefix, --sbin-path, --conf-path, --pid-path, --error-log-path, --http-log-path. The full set of path flags is in auto/options.

Common pitfalls

• auto/configure prints "the HTTP rewrite module requires the PCRE library" — install libpcre2-dev (or libpcre3-dev on older distros) and re-run.
• make install creates logs/ but does not create client_body_temp/, proxy_temp/, etc. nginx will create them on first use if the directives that need them are present.
• error_log debug does nothing unless the binary was built with --with-debug.
• On Linux, listening on port 80/443 as a non-root user requires sudo setcap cap_net_bind_service+ep ./objs/nginx or running with sudo.

For more troubleshooting tips see how-to-contribute/debugging.