NGINX Unit
v. 1.28.0

Installation§

You can install NGINX Unit in four alternative ways:

  • Choose from our official binary packages for a few popular systems. They’re as easy to use as any other packaged software and suit most purposes straight out of the box.
  • If your preferred OS or language version is missing from the official package list, try third-party repositories. Be warned, though: we don’t maintain them.
  • Run our official Docker images, prepackaged with varied language combinations.
  • To fine-tune Unit to your goals, download the sources, install the toolchain, and build a custom binary from scratch; just make sure you know what you’re doing.

Prerequisites§

Unit compiles and runs on various Unix-like operating systems, including:

  • FreeBSD 10 or later
  • Linux 2.6 or later
  • macOS 10.6 or later
  • Solaris 11

It also supports most modern instruction set architectures, such as:

  • ARM
  • IA-32
  • PowerPC
  • MIPS
  • S390X
  • x86-64

App languages and platforms that Unit can run (including several versions of the same language):

  • Go 1.6 or later
  • Java 8 or later
  • Node.js 8.11 or later
  • PHP 5, 7, 8
  • Perl 5.12 or later
  • Python 2.6, 2.7, 3
  • Ruby 2.0 or later

Optional dependencies:

Official Packages§

Installing an official precompiled Unit binary package is best on most occasions; they’re available for:

The packages include core executables, developer files, and support for individual languages. We also maintain a Homebrew tap for macOS users and a module for Node.js at the npm registry.

Note

For details of packaging custom modules that install alongside the official Unit, see here.

Repo Installation Script

We provide a script that adds our official repos on the systems we support:

$ curl -sL 'https://unit.nginx.org/_downloads/setup-unit.sh' | sudo -E bash

Use it at your discretion; explicit steps are provided below for each distribution.

Amazon Linux§

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/amzn2/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc8 unit-perl  \
          unit-php unit-python27 unit-python37
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.22+ packages aren’t built for Amazon Linux AMI. This distribution is obsolete; please update.

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/amzn/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc8 unit-perl unit-php  \
          unit-python27 unit-python34 unit-python35 unit-python36
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

CentOS§

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/centos/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc8 unit-jsc11  \
          unit-perl unit-php unit-python27 unit-python36
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.20+ packages aren’t built for CentOS 6. This distribution is obsolete; please update.

Supported architectures: i386, x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/centos/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc8 unit-php unit-python
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Debian§

Supported architectures: i386, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/debian/ bullseye unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/debian/ bullseye unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc11 unit-perl  \
          unit-php unit-python2.7 unit-python3.9 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Supported architectures: i386, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/debian/ buster unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/debian/ buster unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc11 unit-perl  \
          unit-php unit-python2.7 unit-python3.7 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.22+ packages aren’t built for Debian 9.

Supported architectures: i386, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/debian/ stretch unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/debian/ stretch unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc8 unit-perl  \
          unit-php unit-python2.7 unit-python3.5 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Fedora§

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/fedora/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc11 unit-jsc8 unit-perl  \
          unit-php unit-python39 unit-python310 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.27+ packages aren’t built for Fedora 33 and Fedora 34. These distributions are obsolete; please update.

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/fedora/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc11 unit-jsc8 unit-perl  \
          unit-php unit-python39 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.24+ packages aren’t built for Fedora 32. These distributions are obsolete; please update.

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/fedora/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc11 unit-jsc8 unit-perl  \
          unit-php unit-python38 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.20+ packages aren’t built for Fedora 30; 1.22+ packages aren’t built for Fedora 31. These distributions are obsolete; please update.

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/fedora/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc11 unit-jsc8 unit-perl  \
          unit-php unit-python27 unit-python37 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.20+ packages aren’t built for Fedora 29. This distribution is obsolete; please update.

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/fedora/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc8 unit-perl  \
          unit-php unit-python27 unit-python37 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

RHEL§

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/rhel/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-go unit-jsc8 unit-jsc11  \
          unit-perl unit-php unit-python39
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Supported architecture: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/rhel/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc8 unit-jsc11  \
          unit-perl unit-php unit-python27 unit-python36
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.20+ packages aren’t built for RHEL 6. This distribution is obsolete; please update.

Supported architectures: i386, x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

    [unit]
    name=unit repo
    baseurl=https://packages.nginx.org/unit/rhel/$releasever/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc8 unit-perl  \
          unit-php unit-python
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit

Note

Use the same steps for binary-compatible distributions such as AlmaLinux, Oracle Linux, or Rocky Linux.

Ubuntu§

Supported architectures: arm64, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ jammy unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ jammy unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-go unit-jsc11 unit-jsc16 unit-jsc17 unit-jsc18  \
                  unit-perl unit-php unit-python2.7 unit-python3.10 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.28+ packages aren’t built for Ubuntu 21.10. This distribution is obsolete; please update.

Supported architectures: arm64, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ impish unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ impish unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc11 unit-jsc16 unit-jsc17 unit-jsc18  \
                  unit-perl unit-php unit-python2.7 unit-python3.9 unit-python3.10 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.27+ packages aren’t built for Ubuntu 21.04. This distribution is obsolete; please update.

Supported architectures: arm64, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ hirsute unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ hirsute unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc11 unit-jsc15 unit-jsc16 unit-jsc17  \
                  unit-perl unit-php unit-python2.7 unit-python3.9 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.25+ packages aren’t built for Ubuntu 20.10. This distribution is obsolete; please update.

Supported architectures: arm64, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ groovy unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ groovy unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc11 unit-jsc13 unit-jsc14 unit-jsc15  \
                  unit-perl unit-php unit-python3.8 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Supported architectures: arm64, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ focal unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ focal unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc11 unit-perl  \
          unit-php unit-python2.7 unit-python3.8 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.20+ packages aren’t built for Ubuntu 19.10. This distribution is obsolete; please update.

Supported architecture: x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ eoan unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ eoan unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc11 unit-perl  \
          unit-php unit-python2.7 unit-python3.7 unit-python3.8 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Supported architectures: arm64, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ bionic unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ bionic unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc8 unit-jsc11 unit-perl  \
          unit-php unit-python2.7 unit-python3.6 unit-python3.7 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Warning

Unit’s 1.24+ packages aren’t built for Ubuntu 16.04. This distribution is obsolete; please update.

Supported architectures: arm64, i386, x86-64.

  1. Download and save NGINX’s signing key:

    # curl --output /usr/share/keyrings/nginx-keyring.gpg  \
          https://unit.nginx.org/keys/nginx-keyring.gpg
    

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

    deb [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ xenial unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ xenial unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc8 unit-perl unit-php  \
          unit-python2.7 unit-python3.5 unit-ruby
    # systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup
    

Runtime details:

Control socket /var/run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit

Homebrew§

To install Unit on macOS, use the official Homebrew tap:

$ brew install nginx/unit/unit

This deploys the core Unit binary and the prerequisites for the Node.js language module.

To install the Java, Perl, Python, and Ruby language modules from Homebrew:

$ brew install unit-java unit-perl unit-python unit-python3 unit-ruby
# pkill unitd  # Stop Unit
# unitd        # Start Unit to pick up any changes in language module setup

Runtime details:

Control socket /usr/local/var/run/unit/control.sock
Log file /usr/local/var/log/unit/unit.log
Non-privileged user and group nobody

Node.js§

Unit’s npm-hosted Node.js module is called unit-http. Install it to run Node.js apps on Unit:

  1. First, install the unit-dev/unit-devel package; it’s needed to build unit-http.

  2. Next, build and install unit-http globally (this requires npm and node-gyp):

    # npm install -g --unsafe-perm unit-http
    

    Warning

    The unit-http module is platform dependent due to optimizations; you can’t move it across systems with the rest of node-modules. Global installation avoids such scenarios; just relink the migrated app.

  3. It’s entirely possible to run Node.js apps on Unit without mentioning unit-http in your app sources. However, you can explicitly use unit-http in your code instead of the built-in http, but mind that such frameworks as Express may require extra changes.

If you update Unit later, make sure to update the module as well:

# npm update -g --unsafe-perm unit-http

Note

You can also configure and install the unit-http module from sources.

Startup and Shutdown§

Enable Unit to launch automatically at system startup:

# systemctl enable unit

Start or restart Unit:

# systemctl restart unit

Stop a running Unit:

# systemctl stop unit

Disable Unit’s automatic startup:

# systemctl disable unit

Start Unit as a daemon:

# unitd

Stop all Unit’s processes:

# pkill unitd

For startup options, see below.

Note

Restarting Unit is necessary after installing or uninstalling any language modules to pick up the changes.

Community Repositories§

Warning

These distributions are maintained by respective communities, not NGINX. Proceed with caution.

To install Unit’s core executables from the Alpine Linux packages:

# apk update
# apk upgrade
# apk add unit

To install service manager files and specific language modules:

# apk add unit-openrc unit-perl unit-php7 unit-python3 unit-ruby
# service unit restart  # Necessary for Unit to pick up any changes in language module setup

Runtime details:

Control socket /run/control.unit.sock
Log file /var/log/unit.log
Non-privileged user and group unit
Startup and shutdown
# service unit enable
# service unit restart
# service unit stop
# service unit disable

To install Unit’s core executables and specific language modules from the Sisyphus packages:

# apt-get update
# apt-get install unit
# apt-get install unit-perl unit-php unit-python3 unit-ruby
# service unit restart  # Necessary for Unit to pick up any changes in language module setup

Versions of these packages with the *-debuginfo suffix contain symbols for debugging.

Runtime details:

Control socket /run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group _unit (mind the _ prefix)
Startup and shutdown
# service unit enable
# service unit restart
# service unit stop
# service unit disable

To install Unit’s core executables and all language modules, clone the Arch User Repository (AUR):

$ git clone https://aur.archlinux.org/nginx-unit.git
$ cd nginx-unit

Before proceeding further, verify that the PKGBUILD and the accompanying files aren’t malicious or untrustworthy. AUR packages are user produced without pre-moderation; use them at your own risk.

Next, build the package:

$ makepkg -si

Runtime details:

Control socket /run/nginx-unit.control.sock
Log file /var/log/nginx-unit.log
Non-privileged user and group nobody
Startup and shutdown
# systemctl enable unit
# systemctl restart unit
# systemctl stop unit
# systemctl disable unit

To install Unit from FreeBSD packages, get the core package and other packages you need:

# pkg install -y unit
# pkg install -y libunit
# pkg install -y unit-java8  \
                 unit-perl5.32  \
                 unit-php73 unit-php74 unit-php80  \
                 unit-python37  \
                 unit-ruby3.0
# service unitd restart  # Necessary for Unit to pick up any changes in language module setup

To install Unit from FreeBSD ports, start by updating your port collection.

With portsnap:

# portsnap fetch update

With svn:

# svn update /usr/ports

Next, browse to the port path to build and install the core Unit port:

# cd /usr/ports/www/unit/
# make
# make install

Repeat the steps for the other ports you need: libunit (required to install the Node.js module and build Go apps), unit-java, unit-perl, unit-php, unit-python, or unit-ruby. Having done that, restart Unit:

# service unitd restart  # Necessary for Unit to pick up any changes in language module setup

Runtime details:

Control socket /var/run/unit/control.unit.sock
Log file /var/log/unit/unit.log
Non-privileged user and group www
Startup and shutdown
# service unitd enable
# service unitd restart
# service unitd stop
# service unitd disable

To install Unit using Portage, update the repository and install the package:

# emerge --sync
# emerge www-servers/nginx-unit

To install specific language modules and features, apply the corresponding USE flags.

Runtime details:

Control socket /run/nginx-unit.sock
Log file /var/log/nginx-unit
Non-privileged user and group nobody
Startup and shutdown
# rc-update add nginx-unit
# rc-service nginx-unit restart
# rc-service nginx-unit stop
# rc-update del nginx-unit

To install Unit’s core package and the other packages you need from the NetBSD Package Collection:

# pkg_add unit
# pkg_add libunit
# pkg_add unit-perl  \
          unit-python2.7  \
          unit-python3.6 unit-python3.7 unit-python3.8 unit-python3.9
# service unit restart  # Necessary for Unit to pick up any changes in language module setup

To build Unit manually, start by updating the package collection:

# cd /usr/pkgsrc && cvs update -dP

Next, browse to the package path to build and install the core Unit binaries:

# cd /usr/pkgsrc/www/unit/
# make build install

Repeat the steps for the other packages you need: libunit (required to install the Node.js module and build Go apps), unit-perl, unit-php, unit-python, or unit-ruby. Having done that, restart Unit:

# service unit restart  # Necessary for Unit to pick up any changes in language module setup

Runtime details:

Control socket /var/run/unit/control.unit.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit
Startup and shutdown

First, add Unit’s startup script to the /etc/rc.d/ directory:

# cp /usr/pkg/share/examples/rc.d/unit /etc/rc.d/

After that, you can start and stop Unit as follows:

# service unit restart
# service unit stop

To enable or disable Unit’s automatic startup, edit /etc/rc.conf:

# Enable service:
unit=YES

# Disable service:
unit=NO

To install Unit’s core executables and all language modules using the Nix package manager, update the channel, check if Unit’s available, and install the package:

$ nix-channel --update
$ nix-env -qa 'unit'
$ nix-env -i unit

This installs most embedded language modules and such features as SSL or IPv6 support. For a full list of optionals, see the package definition; for a .nix configuration file defining an app, see this sample.

Runtime details:

Control socket /run/unit/control.unit.sock
Log file /var/log/unit/unit.log
Non-privileged user and group unit
Startup and shutdown

Add services.unit.enable = true; to /etc/nixos/configuration.nix and rebuild the system configuration:

# nixos-rebuild switch

After that, use systemctl:

# systemctl enable unit
# systemctl restart unit
# systemctl stop unit
# systemctl disable unit

To install Unit from OpenBSD packages, get the core package and other packages you need:

# pkg_add unit
# pkg_add unit-perl
# pkg_add unit-php74
# pkg_add unit-php80
# pkg_add unit-python
# pkg_add unit-ruby
# rcctl restart unit  # Necessary for Unit to pick up any changes in language module setup

To install Unit from OpenBSD ports, start by updating your port collection, for example:

$ cd /usr/
$ cvs -d anoncvs@anoncvs.spacehopper.org:/cvs checkout -P ports

Next, browse to the port path to build and install Unit:

$ cd /usr/ports/www/unit/
$ make
# make install

This also installs the language modules for Perl, Python, and Ruby; other modules can be built and installed from source. Having done that, restart Unit:

# rcctl restart unit  # Necessary for Unit to pick up any changes in language module setup

Runtime details:

Control socket /var/run/unit/control.unit.sock
Log file /var/log/unit/unit.log
Non-privileged user and group _unit
Startup and shutdown
# rcctl enable unit
# rcctl restart unit
# rcctl stop unit
# rcctl disable unit

Remi’s RPM repository, which hosts the latest versions of the PHP stack for CentOS, Fedora, and RHEL, also has the core Unit package and the PHP modules.

To use Remi’s versions of Unit’s packages, configure Remi’s RPM repo first. Remi’s PHP language modules are also compatible with the core Unit package from our own repository.

Next, install Unit and the PHP modules you want:

# yum install --enablerepo=remi unit  \
      php54-unit-php php55-unit-php php56-unit-php  \
      php70-unit-php php71-unit-php php72-unit-php php73-unit-php php74-unit-php  \
      php80-unit-php
# systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup

Runtime details:

Control socket /run/unit/control.sock
Log file /var/log/unit/unit.log
Non-privileged user and group nobody
Startup and shutdown
# systemctl enable unit
# systemctl restart unit
# systemctl stop unit
# systemctl disable unit

If you use SCLo Software Collections, you can install Unit’s PHP modules as packages from the corresponding repo. Besides other dependencies, the packages require the core Unit installation.

CentOS:

# yum install centos-release-scl
# yum install --enablerepo=centos-sclo-sclo \
              sclo-php72-unit-php sclo-php73-unit-php
# systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup

RHEL:

# cd /etc/yum.repos.d/
# curl -O https://copr.fedorainfracloud.org/coprs/rhscl/centos-release-scl/repo/epel-7/rhscl-centos-release-scl-epel-7.repo
# yum install centos-release-scl
# yum install --enablerepo=centos-sclo-sclo \
              sclo-php72-unit-php sclo-php73-unit-php
# systemctl restart unit  # Necessary for Unit to pick up any changes in language module setup

Runtime details: see CentOS, RHEL, and Startup and Shutdown.

Docker Images§

Unit’s Docker images come in several language-specific flavors:

Tag Description
1.28.0-minimal No language modules; based on the debian:buster-slim image.
1.28.0-go1.19 Single-language image based on the golang:1.19 image.
1.28.0-jsc11 Single-language image based on the eclipse-temurin:11-jdk image.
1.28.0-node16 Single-language image based on the node:16 image.
1.28.0-perl5.36 Single-language image based on the perl:5.36 image.
1.28.0-php8.1 Single-language image based on the php:8.1-cli image.
1.28.0-python3.10 Single-language image based on the python:3.10 image.
1.28.0-ruby3.1 Single-language image based on the ruby:3.1 image.
Customizing Language Versions in Docker Images

To create a Unit image with a different language version, clone the sources and rebuild them locally on a machine with Docker installed. The build command has the following format:

$ make build-<language name><language version> VERSION_<language name>=<language version>

The make utility parses the command line to extract the language name and version; these values must reference an existing official language image to be used as the base for the build. If not sure whether an official image exists for a specific language version, follow the links in the tag table above.

The language name can be go, jsc, node, perl, php, python, or ruby; the version is defined as <major>.<minor>, except for jsc and node that take only major version numbers (as exemplified by the tag table). Thus, to create a local image based on Python 3.6 and tagged as unit:1.28.0-python3.6:

$ git clone https://github.com/nginx/unit
$ cd unit
$ git checkout 1.28.0  # Optional; use to choose a specific Unit version
$ cd pkg/docker/
$ make build-python3.6 VERSION_python=3.6

For details, see the Makefile. For other customization scenarios, see the Docker howto.

Images With Pre-1.22.0 Unit Versions

Before Unit 1.22.0 was released, the following tagging scheme was used:

Tag Description
<version>-full Contains modules for all languages that Unit currently supports.
<version>-minimal No language modules are included.
<version>-<language> A specific language module such as 1.21.0-ruby2.3 or 1.21.0-python2.7.

You can obtain the images from these sources:

To install and run Unit from NGINX’s repository at Docker Hub:

$ docker pull docker.io/nginx/unit:TAG
$ docker run -d docker.io/nginx/unit:TAG

To install and run Unit from NGINX’s repository at Amazon ECR Public Gallery:

$ docker pull public.ecr.aws/nginx/unit:TAG
$ docker run -d public.ecr.aws/nginx/unit:TAG

To install and run Unit from tarballs stored on our website:

$ curl -O https://packages.nginx.org/unit/docker/1.28.0/nginx-unit-TAG.tar.gz
$ curl -O https://packages.nginx.org/unit/docker/1.28.0/nginx-unit-TAG.tar.gz.sha512
$ sha512sum -c nginx-unit-TAG.tar.gz.sha512
      nginx-unit-TAG.tar.gz: OK

$ docker load < nginx-unit-TAG.tar.gz

Runtime details:

Control socket /var/run/control.unit.sock
Log file Forwarded to the Docker log collector
Non-privileged user and group unit

For more details, see the repository pages (Docker Hub, Amazon ECR Public Gallery) and our Docker howto.

Initial Configuration§

Official images support initial container configuration, implemented with an ENTRYPOINT script.

First, the script checks the Unit state directory (/var/lib/unit/ in official images) of the container. If it’s empty, the script processes certain file types in the container’s /docker-entrypoint.d/ directory:

File Type Purpose/Action
.pem Certificate bundles are uploaded under respective names: cert.pem to certificates/cert.
.json Configuration snippets are uploaded as to the config section of Unit’s configuration.
.sh Shell scripts that run in the container after the .pem and .json files are uploaded.

Note

The script issues warnings about any other file types in the /docker-entrypoint.d/ directory. Also, your shell scripts must have execute permissions set.

This mechanism allows you to customize your containers at startup, reuse configurations, and automate your workflows, reducing manual effort. To use the feature, add COPY directives for certificate bundles, configuration fragments, and shell scripts to your Dockerfile derived from an official image:

FROM nginx/unit:1.28.0-minimal
COPY ./*.pem  /docker-entrypoint.d/
COPY ./*.json /docker-entrypoint.d/
COPY ./*.sh   /docker-entrypoint.d/

Note

Mind that running Unit even once populates its state directory; this prevents the script from executing, so this script-based initialization must occur before you run Unit within your derived image.

This feature comes in handy if you want to tie Unit to a certain app configuration for later use. For ad-hoc initialization, you can mount a directory with configuration files to a container at startup:

$ docker run -d --mount \
         type=bind,src=/path/to/config/files/,dst=/docker-entrypoint.d/ \
         nginx/unit:1.28.0-minimal)

Source Code§

You can get Unit’s source code from our official Mercurial repository, its GitHub mirror, or in a tarball.

If you’d like to use Mercurial:

$ hg clone https://hg.nginx.org/unit
$ cd unit

If you prefer Git:

$ git clone https://github.com/nginx/unit
$ cd unit

To download the sources directly from our site:

$ curl -O https://unit.nginx.org/download/unit-1.28.0.tar.gz
$ tar xzf unit-1.28.0.tar.gz
$ cd unit-1.28.0

To build Unit and specific language modules from these sources, refer to the source code howto; to package custom modules, see the module howto.