NGINX Documentation

Installing NGINX Open Source

This article explains how to install NGINX Open Source.

Choosing Between a Stable or a Mainline Version

NGINX Open Source is available in two versions:

  • Mainline – Includes the latest features and bug fixes and is always up to date. It is reliable, but it may include some experimental modules, and it may also have some number of new bugs.
  • Stable – Doesn’t include all of the latest features, but has critical bug fixes that are always backported to the mainline version. We recommend the stable version for production servers.

Choosing Between a Prebuilt Package and Compiling from Source

Both the NGINX Open Source mainline and stable versions can be installed in two ways:

  • As a prebuilt binary package. This is a quick and easy way to install NGINX Open Source. The package includes almost all official NGINX modules and is available for most popular operating systems. See Installing a Prebuilt Package.
  • As binaries you compile from source. This way is more flexible: you can add particular modules, including third‑party modules, or apply the latest security patches. See Compiling and Installing from Source for details.

Installing a Prebuilt Package

Installing NGINX Open Source from a package is much easier and faster than building from source, but building from source enables you to compile in non-standard modules. Prebuilt packages are available for most popular Linux distributions, including CentOS, Debian, Red Hat Enterprise Linux (RHEL), SUSE Linux Enterprise Server (SLES), and Ubuntu. See Linux packages at nginx.org for the list of currently supported operating systems.

Modules Included in a Prebuilt Package

See Configure Arguments at nginx.org for the list of modules included in each prebuilt package.

Installing Prebuilt CentOS and RHEL Packages

NGINX, Inc. provides packages for the following CentOS, Oracle Linux, and RHEL versions:

The package can be installed from:

  • A default RHEL or CentOS repository. This is the quickest way, but generally the provided package is outdated.
  • The official repo at nginx.org. You have to set up the yum repository the first time, but after that the provided package is always up to date.

Installing a Prebuilt CentOS/RHEL Package from an OS Repository

  1. Install the EPEL repository:

    $ sudo yum install epel-release
    
  2. Update the repository and install NGINX Open Source:

    $ sudo yum update
    
  3. Verify the installation:

    $ sudo nginx -v
    nginx version: nginx/1.6.3
    

Installing a Prebuilt CentOS/RHEL Package from the Official NGINX Repository

  1. Set up the yum repository for RHEL or CentOS by creating the file nginx.repo in /etc/yum.repos.d, for example using vi:

    $ sudo vi /etc/yum.repos.d/nginx.repo
    
  2. Add the following lines to nginx.repo:

    [nginx]
    name=nginx repo
    baseurl=https://nginx.org/packages/mainline/<OS>/<OSRELEASE>/$basearch/
    gpgcheck=0
    enabled=1
    

    where:

    • The /mainline element in the pathname points to the latest mainline version of NGINX Open Source; delete it to get the latest stable version

    • <OS> is either rhel or centos

    • <OSRELEASE> is the release number (6, 6._x_, 7, 7._x_ and so on)

      For example, to get the latest mainline package for CentOS 7, insert:

      [nginx]
      name=nginx repo
      baseurl=https://nginx.org/packages/mainline/centos/7/$basearch/
      gpgcheck=0
      enabled=1
      
  3. Save the changes and quit vi (press ESC and type wq at the : prompt).

  4. Update the repository, installing the NGINX Open Source package:

    $ sudo yum update
    
  5. Start NGINX Open Source:

    $ sudo nginx
    
  6. Verify that NGINX Open Source is up and running:

    $ curl -I 127.0.0.1
    HTTP/1.1 200 OK
    Server: nginx/1.13.8
    

Installing Prebuilt Debian Packages

NGINX provides packages for the following Debian operating systems:

The package can be installed from:

  • A default Debian repository. This is the quickest way, but generally the provided package is outdated.
  • The official repo at nginx.org. You have to set up the apt-get repository the first time, but after that the provided package is always up to date.

Installing a Prebuilt Debian Package from an OS Repository

  1. Update the Debian repository information:

    $ sudo apt-get update
    
  2. Install the NGINX Open Source package:

    $ sudo apt-get install nginx
    
  3. Verify the installation:

    $ sudo nginx -v
    nginx version: nginx/1.6.2
    

Installing a Prebuilt Debian Package from the Official NGINX Repository

  1. Download the key used to sign NGINX packages and the repository, and add it to the apt program’s key ring:

    $ sudo wget https://nginx.org/keys/nginx_signing.key
    $ sudo apt-key add nginx_signing.key
    
  2. Edit the /etc/apt/sources.list file, for example with vi:

    $ sudo vi /etc/apt/sources.list
    
  3. Add these lines to sources.list to name the repositories from which the NGINX Open Source can be obtained:

    deb https://nginx.org/packages/mainline/debian/ <CODENAME> nginx
    deb-src https://nginx.org/packages/mainline/debian/ <CODENAME> nginx
    

    where:

    • The /mainline element in the pathname points to the latest mainline version of NGINX Open Source; delete it to get the latest stable version

    • <CODENAME> is the codename of a Debian release

      For example, to get the latest mainline package for Debian 8.2 (“jessie”), insert:

      deb https://nginx.org/packages/mainline/debian/ jessie nginx
      deb-src https://nginx.org/packages/mainline/debian/ jessie nginx
      
  4. Save the changes and quit vi (press ESC and type wq at the : prompt).

  5. Install the NGINX package:

    $ sudo apt-get remove nginx-common
    $ sudo apt-get update
    $ sudo apt-get install nginx
    
  6. Start NGINX Open Source:

    $ sudo nginx
    
  7. Verify that NGINX Open Source is up and running:

    $ curl -I 127.0.0.1
    HTTP/1.1 200 OK
    Server: nginx/1.13.8
    

Installing Prebuilt Ubuntu Packages

NGINX provides packages for the following Ubuntu operating systems:

The package can be installed from:

  • A default Ubuntu repository. This is the quickest way, but generally the provided package is outdated.
  • The official repo at nginx.org. You have to set up the apt-get repository the first time, but after that the provided package is always up to date.

Installing a Prebuilt Ubuntu Package from an Ubuntu Repository

  1. Update the Ubuntu repository information:

    $ sudo apt-get update
    
  2. Install the package:

    $ sudo apt-get install nginx
    
  3. Verify the installation:

    $ sudo nginx -v
    nginx version: nginx/1.4.6 (Ubuntu)
    

Installing a Prebuilt Ubuntu Package from the Official NGINX Repository

  1. Download the key used to sign NGINX packages and the repository, and add it to the apt program’s key ring:

    $ sudo wget https://nginx.org/keys/nginx_signing.key
    $ sudo apt-key add nginx_signing.key
    
  2. Edit the /etc/apt/sources.list file, for example with vi:

    $ sudo vi /etc/apt/sources.list
    
  3. Add these lines sources.list to name the repositories from which the NGINX Open Source source can be obtained:

    deb https://nginx.org/packages/mainline/ubuntu/ <CODENAME> nginx
    deb-src https://nginx.org/packages/mainline/ubuntu/ <CODENAME> nginx
    

    where:

    • The /mainline element in the pathname points to the latest mainline version of NGINX Open Source; delete it to get the latest stable version
    • <CODENAME> is the codename of an Ubuntu release

    For example, to get the latest mainline package for Ubuntu 14.04 (“trusty”), add:

    deb https://nginx.org/packages/mainline/ubuntu/ trusty nginx
    deb-src https://nginx.org/packages/mainline/ubuntu/ trusty nginx
    
  4. Save the changes and quit vi (press ESC and type wq at the : prompt).

  5. Install NGINX Open Source:

    $ sudo apt-get remove nginx-common
    $ sudo apt-get update
    $ sudo apt-get install nginx
    
  6. Start NGINX Open Source:

    $ sudo nginx
    
  7. Verify that NGINX Open Source is up and running:

    $ curl -I 127.0.0.1
    HTTP/1.1 200 OK
    Server: nginx/1.13.8
    

Installing SUSE Packages

NGINX provides packages for SUSE Linux Enterprise Server 12 (x86_64).

To download and install the latest stable version, run:

$ zypper addrepo -G -t yum -c 'https://nginx.org/packages/sles/12' nginx
$ zypper install nginx

To download and install the latest mainline version, run:

$ zypper addrepo -G -t yum -c 'https://nginx.org/packages/mainline/sles/12' nginx
$ zypper install nginx

Compiling and Installing from Source

Compiling NGINX Open Source from source affords more flexibility than prebuilt packages: you can add particular modules (from NGINX or third parties), and apply latest security patches.

Installing NGINX Dependencies

Prior to compiling NGINX Open Source from source, you need to install libraries for its dependencies:

  • PCRE – Supports regular expressions. Required by the NGINX Core and Rewrite modules.

    $ wget ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-8.42.tar.gz
    $ tar -zxf pcre-8.42.tar.gz
    $ cd pcre-8.42
    $ ./configure
    $ make
    $ sudo make install
    
  • zlib – Supports header compression. Required by the NGINX Gzip module.

    $ wget http://zlib.net/zlib-1.2.11.tar.gz
    $ tar -zxf zlib-1.2.11.tar.gz
    $ cd zlib-1.2.11
    $ ./configure
    $ make
    $ sudo make install
    
  • OpenSSL – Supports the HTTPS protocol. Required by the NGINX SSL module and others.

    $ wget http://www.openssl.org/source/openssl-1.0.2o.tar.gz
    $ tar -zxf openssl-1.0.2o.tar.gz
    $ cd openssl-1.0.2o
    $ ./Configure darwin64-x86_64-cc --prefix=/usr
    $ make
    $ sudo make install
    

Downloading the Sources

Download the source files for both the stable and mainline versions from nginx.org.

To download and unpack the source for the latest mainline version, run:

$ wget https://nginx.org/download/nginx-1.13.12.tar.gz
$ tar zxf nginx-1.13.12.tar.gz
$ cd nginx-1.13.12

To download and unpack source files for the latest stable version, run:

$ wget https://nginx.org/download/nginx-1.14.0.tar.gz
$ tar zxf nginx-1.14.0.tar.gz
$ cd nginx-1.14.0

Configuring the Build Options

Configure options are specified with the ./configure script that sets up various NGINX parameters, including paths to source and configuration files, compiler options, connection processing methods, and the list of modules. The script finishes by creating the Makefile required to compile the code and install NGINX Open Source.

An example of options to the configure script:

$ ./configure
--sbin-path=/usr/local/nginx/nginx
--conf-path=/usr/local/nginx/nginx.conf
--pid-path=/usr/local/nginx/nginx.pid
--with-pcre=../pcre-8.41
--with-zlib=../zlib-1.2.11
--with-http_ssl_module
--with-stream
--with-mail=dynamic
--add-module=/usr/build/nginx-rtmp-module
--add-dynamic-module=/usr/build/3party_module

Configuring NGINX Paths

The configure script allows you to set paths to NGINX binary and configuration files, and to dependent libraries such as PCRE or SSL, in order to link them statically to the NGINX binary.

--prefix=<PATH>Directory for NGINX files, and the base location for all relative paths set by the other configure script options (excluding paths to libraries) and for the path to the nginx.conf configuration file.Default: /usr/local/nginx.

--sbin-path=<PATH>Name of the NGINX executable file, which is used only during installation.Default: prefix/sbin/nginx

--conf-path=<PATH>Name of the NGINX configuration file. You can, however, always override this value at startup by specifying a different file with the -c <FILENAME> option on the nginx command line.Default: prefix/conf/nginx.conf

--pid-path=<PATH>Name of the nginx.pid file, which stores the process ID of the nginx master process. After installation, the path to the filename can be changed with the pid directive in the NGINX configuration file.Default: prefix/logs/nginx.pid

--error-log-path=<PATH>Name of the primary log file for errors, warnings, and diagnostic data. After installation, the filename can be changed with the the error_log directive in the NGINX configuration file.Default: prefix/logs/error.log

--http-log-path=<PATH>Name of the primary log file for requests to the HTTP server. After installation, the filename can always be changed with the access_log directive in the NGINX configuration file. Default: prefix/logs/access.log

--user=<NAME>Name of the unprivileged user whose credentials are used by the NGINX worker processes. After installation, the name can be changed with the user directive in the NGINX configuration file.Default:nobody

--group=<NAME>Name of the group whose credentials are used by the NGINX worker processes. After installation, the name can be changed with the user directive in the NGINX configuration file.Default: the value set by the --user option

--with-pcre=<PATH>Path to the source for the PCRE library, which is required for regular expressions support in the location directive and the Rewrite module.

--with-pcre-jitBuilds the PCRE library with “just-in-time compilation” support (the pcre_jit directive).

--with-zlib=<PATH>Path to the source for the zlib library, which is required by the Gzip module.

Configuring NGINX GCC Options

With the configure script you can also specify compiler‑related options.

--with-cc-opt="<PARAMETERS>"Additional parameters that are added to the CFLAGS variable.When using the system PCRE library under FreeBSD, the mandatory value is --with-cc-opt="-I /usr/local/include".If the number of files supported by select() needs to be increased, it can also specified here as in this example: --with-cc-opt="-D FD_SETSIZE=2048".

--with-ld-opt="<PARAMETERS>"Additional parameters that are used during linking.When using the system PCRE library under FreeBSD, the mandatory value is --with-ld-opt="-L /usr/local/lib".

Specifying NGINX Connection Processing Methods

With the configure script you can redefine the method for event‑based polling. For more information, see Connection processing methods in the NGINX reference documentation.

--with-select_module, --without-select_moduleEnables or disables building a module that enable NGINX to work with the select() method. The modules is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, or /dev/poll.

--with-poll_module, --without-poll_moduleEnables or disables building a module that enables NGINX to work with the poll() method. The module is built automatically if the platform does not appear to support more appropriate methods such as kqueue, epoll, or /dev/poll.

Selecting the NGINX Modules to Build

NGINX consists of a set of function‑specific modules, which are specified with configure script along with other build options.

Some modules are built by default – they do not have to be specified with the configure script. Default modules can however be explicitly excluded from the NGINX binary with the --without-<MODULE-NAME> option on the configure script.

Modules not included by default, as well as third‑party modules, must be explicitly specified in the configure script together with other build options. Such modules can be linked to NGINX binary either statically (they are then loaded each time NGINX starts) or dynamically (they are loaded only if associated directives are included in the NGINX configuration file.

Modules Built by Default

If you do not need a module that is built by default, you can disable it by naming it with the --without-<MODULE-NAME> option on the configure script, as in this example which disables the Empty GIF module.

$ ./configure --sbin-path=/usr/local/nginx/nginx --conf-path=/usr/local/nginx/nginx.conf --pid-path=/usr/local/nginx/nginx.pid --with-http_ssl_module --with-stream --with-pcre=../pcre-8.41 --with-zlib=../zlib-1.2.11 --without-http_empty_gif_module

Including Modules Not Built by Default

Many NGINX modules are not built by default, and must be listed on the configure command line to be built.

The mail, stream, geoip, image_filter, perl and xslt modules can be compiled as dynamic. See Dynamic Modules for details.

An example of the configure command that includes nondefault modules:

$ ./configure --sbin-path=/usr/local/nginx/nginx --conf-path=/usr/local/nginx/nginx.conf --pid-path=/usr/local/nginx/nginx.pid --with-pcre=../pcre-8.41 --with-zlib=../zlib-1.2.11 --with-http_ssl_module --with-stream --with-mail

--with-cpp_test_moduleTests the C++ compatibility of header files.

--with-debugEnables the debugging log.

--with-file-aioEnables asynchronous I/O.

--with-google_perftools_moduleAllows using Google Performance tools library.

--with-http_addition_moduleAdds text before and after a response. For information about the directives defined by the module, see the module documentation.

--with-http_auth_request_moduleImplements client authorization based on the result of a subrequest. For information about the directives defined by the module, see the module documentation.

--with-http_dav_moduleEnables file management automation using the WebDAV protocol. For information about the directives defined by the module, see the module documentation.

--with-http_degradation_moduleAllows returning an error when a memory size exceeds the defined value.

--with-http_flv_moduleProvides pseudo-streaming server-side support for Flash Video (FLV) files. For information about the directives defined by the module, see the module documentation.

--with-http_geoip_moduleEnables creating variables whose values depend on the client IP address. The module uses MaxMind GeoIP databases. For information about the directives defined by the module, see the module documentation. To compile as a separate dynamic module instead, change the option to --with-http_geoip_module=dynamic.

--with-http_gunzip_moduleDecompresses responses with Content-Encoding: gzip for clients that do not support the zip encoding method. For information about the directives defined by the module, see the module documentation.

--with-http_gzip_static_moduleAllows sending precompressed files with the .gz filename extension instead of regular files. For information about the directives defined by the module, see the module documentation.

--with-http_image_filter_moduleTransforms images in JPEG, GIF, and PNG formats. The module requires the LibGD library. For information about the directives defined by the module, see module documentation. To compile as a separate dynamic module instead, change the option to --with-http_image_filter_module=dynamic.

--with-http_mp4_moduleProvides pseudo-streaming server-side support for MP4 files. For information about the directives defined by the module, see the module documentation.

--with-http_perl_moduleUsed to implement location and variable handlers in Perl and insert Perl calls into SSI. Requires the PERL library. For information about the directives defined by the module, see the module documentation. To compile as a separate dynamic module instead, change the option to --with-http_perl_module=dynamic.

--with-http_random_index_moduleProcesses requests ending with the slash character (‘/’) and picks a random file in a directory to serve as an index file. For information about the directives defined by the module, see the module documentation.

--with-http_realip_moduleChanges the client address to the one sent in the specified header field. For information about the directives defined by the module, see the module documentation.

--with-http_secure_link_moduleUsed to check authenticity of requested links, protect resources from unauthorized access, and limit link lifetime. For information about the directives defined by the module, see the module documentation.

--with-http_slice_moduleAllows splitting a request into subrequests, each subrequest returns a certain range of response. Provides more effective caching of large files. For information about the directives defined by the module, see the module documentation.

--with-http_ssl_moduleEnables HTTPS support. Requires an SSL library such as OpenSSL. For information about the directives defined by the module, see the module documentation.

--with-http_stub_status_moduleProvides access to basic status information. For information about the directives defined by the module, see the module documentation. Note that NGINX Plus customers do not require this module as they are already provided with extended status metrics and interactive dashboard.

--with-http_sub_moduleModifies a response by replacing one specified string by another. For information about the directives defined by the module, see the module documentation.

--with-http_xslt_moduleTransforms XML responses using one or more XSLT stylesheets. The module requires the Libxml2 and XSLT libraries. For information about the directives defined by the module, see the module documentation. To compile as a separate dynamic module instead, change the option to --with-http_xslt_module=dynamic.

--with-http_v2_moduleEnable support for HTTP/2. For information about the directives defined by the module, see the module documentation and The HTTP/2 Module in NGINX on the NGINX blog for details.

--with-mailEnables mail proxy functionality. For information about the directives defined by the module, see the module documentation. To compile as a separate dynamic module instead, change the option to --with-mail=dynamic.

--with-mail_ssl_moduleProvides support for a mail proxy server to work with the SSL/TLS protocol. Requires an SSL library such as OpenSSL. For information about the directives defined by the module, see the module documentation.

--with-streamEnables the TCP and UDP proxy functionality. For information about the directives defined by the module, see the module documentation. To compile as a separate dynamic module instead, change the option to --with-stream=dynamic.

--with-stream_ssl_moduleProvides support for a stream proxy server to work with the SSL/TLS protocol. Requires an SSL library such as OpenSSL. For information about the directives defined by the module, see the module documentation.

--with-threadsEnables NGINX to use thread pools. For details, see Thread Pools in NGINX Boost Performance 9x! on the NGINX blog.

Including Third-Party Modules

You can extend NGINX functionality by compiling NGINX Open Source with your own module or a third‑party module. Some third‑party modules are listed in the NGINX Wiki. Use third‑party modules at your own risk as their stability is not guaranteed.

Statically Linked Modules

Most modules built into NGINX Open Source are statically linked: they are built into NGINX Open Source at compile time and are linked to the NGINX binary statically. These modules can be disabled only by recompiling NGINX.

To compile NGINX Open Source with a statically linked third‑party module, include the --add-module=<PATH> option on the configure command, where <PATH> is the path to the source code (this example is for the RTMP module):

$  ./configure ... --add-module=/usr/build/nginx-rtmp-module
Dynamically Linked Modules

NGINX modules can also be compiled as a shared object (*.so file) and then dynamically loaded into NGINX Open Source at runtime. This provides more flexibility, as the module can be loaded or unloaded at any time by adding or removing the associated load_module directive in the NGINX configuration file and reloading the configuration. Note that the module itself must support dynamic linking.

To compile NGINX Open Source with a dynamically loaded third‑party module, include the --add-dynamic-module=<PATH> option on the configure command, where <PATH> is the path to the source code:

$  ./configure ... --add-dynamic-module=<PATH>

The resulting *.so files are written to the the prefix/modules/ directory, where the prefix is a directory for server files such as /usr/local/nginx/.

To load a dynamic module, add the load_module directive to the NGINX configuration after installation.

For more information, see Compiling Third‑Party Dynamic Modules for NGINX and NGINX Plus on the NGINX blog and Extending NGINX in the Wiki.

Completing the Installation from Source

  • Compile and install the build:

    $ make
    $ sudo make install
    
  • After the installation is finished, start NGINX Open Source:

    $ sudo nginx