NGINX Unit
v. 1.32.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 Docker official 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
  • WebAssembly Components WASI 0.2

Optional dependencies:

  • OpenSSL 1.0.1 or later for TLS support
  • PCRE (8.0 or later) or PCRE2 (10.23 or later) for regular expression matching
  • The njs scripting language
  • Wasmtime for WebAssembly Support

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:

$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit
# ./setup-unit repo-config

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/amzn/2023/$basearch/
    gpgcheck=0
    enabled=1
    
  2. Install the core package and other packages you need:

    # yum install unit
    # yum install unit-devel unit-jsc17 unit-perl  \
          unit-php unit-python39 unit-python311 unit-wasm
    # 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/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 unit-wasm
    # 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

Debian§

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/debian/ bookworm unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/debian/ bookworm unit
    
  3. Install the core package and other packages you need:

    # apt update
    # apt install unit
    # apt install unit-dev unit-jsc17 unit-perl  \
          unit-php unit-python3.11 unit-ruby unit-wasm
    # 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/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 unit-wasm
    # 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 Debian 10. This distribution is obsolete; please update.

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. This distribution is obsolete; please update.

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-jsc8 unit-jsc11 unit-perl  \
          unit-php unit-python311 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

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-jsc11 unit-perl  \
          unit-php unit-python311 unit-ruby unit-wasm
    # 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.31+ packages aren’t built for Fedora 36 and Fedora 35. 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-jsc8 unit-jsc11 unit-perl  \
          unit-php unit-python39 unit-python310 unit-ruby unit-wasm
    # 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-jsc8 unit-jsc11 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-jsc8 unit-jsc11 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-jsc8 unit-jsc11 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 and derivatives§

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 unit-wasm
    # 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 unit-python38 unit-python39 unit-wasm
    # 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

Official packages for CentOS 7.x are also available.

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 these steps for binary-compatible distributions: AlmaLinux, CentOS, 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/ lunar unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ lunar 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-jsc17 unit-jsc18 unit-jsc19 unit-jsc20  \
                  unit-perl unit-php unit-python3.11 unit-ruby unit-wasm
    # 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.31+ packages aren’t built for Ubuntu 22.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/ kinetic unit
    deb-src [signed-by=/usr/share/keyrings/nginx-keyring.gpg] https://packages.nginx.org/unit/ubuntu/ kinetic 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-jsc17 unit-jsc18 unit-jsc19  \
                  unit-perl unit-php unit-python2.7 unit-python3.10 unit-ruby unit-wasm
    # 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/ 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 unit-wasm
    # 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 unit-wasm
    # 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

Warning

Unit’s 1.31+ packages aren’t built for Ubuntu 18.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/ 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

macOS§

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-php 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 (Intel), /opt/homebrew/var/run/unit/control.sock (Apple Silicon)
Log file /usr/local/var/log/unit/unit.log (Intel), /opt/homebrew/var/log/unit/unit.log (Apple Silicon)
Non-privileged user and group nobody

Note

To run Unit as root on macOS:

$ export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
$ sudo --preserve-env=OBJC_DISABLE_INITIALIZE_FORK_SAFETY /path/to/unitd ...

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.

Working with multiple Node.js versions

To use Unit with multiple Node.js versions side by side, we recommend Node Version Manager:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/x.y.z/install.sh | bash

Install the versions you need and select the one you want to use with Unit:

$ nvm install 18
$ nvm install 16
$ nvm use 18
      Now using node v18.12.1 (npm v8.19.2)

Having selected the specific version, install the node-gyp module:

$ npm install -g node-gyp

Next, clone the Unit source code to build a unit-http module for the selected Node.js version:

$ hg clone https://hg.nginx.org/unit
$ cd unit
$ pwd
      /home/user/unit

$ ./configure
$ ./configure nodejs

      configuring nodejs module
      checking for node ... found
       + node version v18.12.1
      checking for npm ... found
       + npm version 8.19.2
      checking for node-gyp ... found
       + node-gyp version v9.3.0

Point to Unit’s header files and libraries in the source code directory to build the module:

$ CPPFLAGS="-I/home/user/unit/include/" LDFLAGS="-L/home/user/unit/lib/"  \
      make node-install

$ npm list -g

      /home/vagrant/.nvm/versions/node/v18.12.1/lib
      ├── corepack@0.14.2
      ├── node-gyp@9.3.0
      ├── npm@8.19.2
      └── unit-http@1.29.0

That’s all; use the newly built module to run your Node.js apps on Unit as usual.

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 their respective communities, not NGINX. Use them 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.36  \
                 unit-php81 unit-php82 unit-php83  \
                 unit-python39  \
                 unit-ruby3.1  \
                 unit-wasm
# 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 git:

# cd /usr/ports && git pull

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, unit-ruby, or unit-wasm. After 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 Packages Collection:

# pkg_add unit
# pkg_add libunit
# pkg_add unit-perl  \
          unit-python2.7  \
          unit-python3.8 unit-python3.9 unit-python3.10 unit-python3.11 unit-python3.12  \
          unit-ruby31 unit-ruby32
# 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.

Note that unit-php packages require the PHP package to be built with the php-embed option. To enable the option for lang/php82:

# echo "PKG_OPTIONS.php82=php-embed" >> /etc/mk.conf

After 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-php81
# pkg_add unit-php82
# pkg_add unit-php83
# 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, PHP, Python, and Ruby; other modules can be built and installed from source. After 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 Fedora and RHEL, also has the core Unit package and the PHP modules.

To use Remi’s versions of Unit’s packages, configure the repository 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 php81-unit-php php82-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

Docker Images§

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

Tag Description
1.32.0-minimal No language modules; based on the debian:bullseye-slim image.
1.32.0-go1.21 Single-language; based on the golang:1.21 image.
1.32.0-jsc11 Single-language; based on the eclipse-temurin:11-jdk image.
1.32.0-node20 Single-language; based on the node:20 image.
1.32.0-perl5.38 Single-language; based on the perl:5.38 image.
1.32.0-php8.2 Single-language; based on the php:8.2-cli image.
1.32.0-python3.11 Single-language; based on the python:3.11 image.
1.32.0-ruby3.2 Single-language; based on the ruby:3.2 image.
1.32.0-wasm Single-language; based on the debian:bullseye-slim image.
Customizing language versions in Docker images

To build a custom language version image, clone and rebuild the sources locally with Docker installed:

$ make build-<language name><language version> VERSIONS_<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.

Note

Unit relies on the official Docker images, so any customization method offered by their maintainers is equally applicable; to tailor a Unit image to your needs, see the quick reference for its base image.

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 seen in the tag table). Thus, to create an image with Python 3.10 and tag it as unit:|version|-python3.10:

$ git clone https://github.com/nginx/unit
$ cd unit
$ git checkout 1.32.0  # Optional; use to choose a specific Unit version
$ cd pkg/docker/
$ make build-python3.10 VERSIONS_python=3.10

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

Images with pre-1.29.1 Unit versions
Before Unit 1.29.1 was released, our Docker images were available from the official NGINX repository on Docker Hub.
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 then supported.
<version>-minimal No language modules were 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 official builds at Docker Hub:

$ docker pull unit:TAG
$ docker run -d 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

Warning

Unit’s 1.30+ image tarballs aren’t published on the website; this channel is deprecated.

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

$ curl -O https://packages.nginx.org/unit/docker/1.29.1/nginx-unit-TAG.tar.gz
$ curl -O https://packages.nginx.org/unit/docker/1.29.1/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§

The official images support initial container configuration, implemented with an ENTRYPOINT script. First, the script checks the Unit state directory in the container (/var/lib/unit/). 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, uploaded under respective names: cert.pem to /certificates/cert.
.json Configuration snippets, uploaded to the /config section of Unit’s configuration.
.sh Shell scripts, run after the .pem and .json files are uploaded; must be executable.

The script warns about any other file types in /docker-entrypoint.d/.

This mechanism enables customizing your containers at startup, reusing configurations, and automating workflows to reduce 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 unit:1.32.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 in your derived container.

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/  \
         unit:1.32.0-minimal)

Source Code§

You can get Unit’s source code from our official GitHub repository or as a tarball.

$ git clone https://github.com/nginx/unit            # Latest updates to the repository
$ # -- or --
$ git clone -b 1.32.0 https://github.com/nginx/unit  # Specific version tag; see https://github.com/nginx/unit/tags
$ cd unit
$ curl -O https://sources.nginx.org/unit/unit-1.32.0.tar.gz
$ tar xzf unit-1.32.0.tar.gz
$ cd unit-1.32.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.