Nginx - Build and add dynamic module (pagespeed, nginx-module-vts, )


This page will show you how to add module to an existent nginx installation

If you want to add another module to an existing installation, you need to build it against the source as dynamic module (.so) and add it to your configuration.


Nginx preparation steps

Install the Nginx Dependencies


If you have installed Nginx from a package, you may need to install them

yum install -y redhat-rpm-config openssl-devel gc gcc gcc-c++ pcre-devel zlib-devel make wget libxml2-devel libxslt-devel gd-devel perl-ExtUtils-Embed GeoIP-devel gperftools gperftools-devel libatomic_ops-devel perl-ExtUtils-Embed

Download and zunip the Nginx source

  • Check your Nginx version
nginx -v
  • Download
# example
  • unzip
tar zxf nginx-1.16.1.tar.gz

Module preparation steps

Install the module dependencies

Install the dependencies of your module


  • pagespeed
yum  install -y  gcc-c++ pcre-devel zlib-devel make unzip libuuid-devel

Download the module source

Example :

  • pagespeed on x64. See the whole documentation here
# psol page speed dependency download
cd incubator-pagespeed-ngx-
tar zxf

Configure and build

  • Get the actual configuration arguments
nginx -V 
# or
nginx -V 2>&1 | grep 'configure arguments' | cut --delimiter ':' --fields=2-
  • Add the module as dynamic
cd nginx
./configure \
   CONFIGURE_ARGUMENTS \ # should be replace with the output of nginx -V 
  • Example with pagespeed and a little of magic to extract the actual arguments
cd nginx
IFS=$'\t'; ./configure \
        --add-dynamic-module=../incubator-pagespeed-ngx- \
        $(nginx -V 2>&1 | grep 'configure arguments' | cut --delimiter ':' --fields=2- | sed $'s/ --/\t--/g' | sed $'s/\t--param/ --param/g' | tr -d "'" | cut -c2- )  \
        > configure-stdout-ansible-cmd.log 2>&1
  • build
# or with two process
make -j 2

Copy the shared library

Copy the shared library create into the module path.

  • Get the prefix
nginx -V 2>&1 | grep 'configure arguments' | sed 's/--/\n--/g' | grep prefix

  • Copy
cp ./objs/  /usr/share/nginx/modules
# with pagespeed
cp ./objs/  /usr/share/nginx/modules

Add it to the configuration, test and reload

  • At the top
load_module "modules/";
# with pagespeed
load_module "modules/";
  • Verify the configuration
nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

  • Reload the service
systemctl reload nginx
# FYI: may be also restart ?
systemctl restart nginx

Support is not binary compatible in /etc/nginx/nginx.conf

There is a lot of chance that the configuration arguments passed to the configure steps are not the good one.

See configure_and_build

dlopen failed

nginx: [emerg] dlopen() "/usr/share/nginx/modules/" failed (/usr/share/nginx/modules/ cannot e...ginx.conf:11

selinux may unauthorize the loading of the library.

Discover More
Nginx - Grammar

A page the grammar of Nginx nginx consists of modules which are controlled by directives specified in the configuration file. Directives are divided into simple directives and block directives....
Nginx - Installation

Nginx default installation is to use a package. This default installation install some core module and also the below one. See module:...
Nginx - Log (log_format)

This article is the Web/HTTP log of nginx. The log is: available via the ngx_http_log_module module part of the diagnostic tools. This...

Share this page:
Follow us:
Task Runner