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.

Note

The commands in this document starting with a hash (#) must be run as root or with superuser privileges.

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

Community Repositories§

Warning

These distributions are maintained by their respective communities, not NGINX. Use them with caution.

Alpine

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

ALT

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

Arch

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

FreeBSD

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.2  \
                 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

Gentoo

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

NetBSD

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 unit-ruby33

# 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

Nix

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

OpenBSD

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

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.34.2-minimal`	No language modules; based on the debian:bullseye-slim image.
`1.34.2-go1.21`	Single-language; based on the golang:1.21 image.
`1.34.2-jsc11`	Single-language; based on the eclipse-temurin:11-jdk image.
`1.34.2-node20`	Single-language; based on the node:20 image.
`1.34.2-perl5.38`	Single-language; based on the perl:5.38 image.
`1.34.2-php8.2`	Single-language; based on the php:8.2-cli image.
`1.34.2-python3.11`	Single-language; based on the python:3.11 image.
`1.34.2-ruby3.2`	Single-language; based on the ruby:3.2 image.
`1.34.2-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 |version|  # 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.

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:

Docker Hub

To install and run Unit from official builds at Docker Hub:

$ docker pull unit:TAG

$ docker run -d unit:TAG

Amazon ECR Public Gallery

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

packages.nginx.org

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.34.2-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.34.2-minimal)

Source Code§

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

Git

$ git clone https://github.com/nginx/unit            # Latest updates to the repository

$ # -- or --

$ git clone -b 1.34.2 https://github.com/nginx/unit  # Specific version tag; see https://github.com/nginx/unit/tags

$ cd unit

Tarball

$ curl -O https://sources.nginx.org/unit/unit-1.34.2.tar.gz

$ tar xzf unit-1.34.2.tar.gz

$ cd unit-1.34.2

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

Edit this page

Discuss on GitHub

v. 1.34.2

Installation§

Prerequisites§

Official packages§

Amazon Linux§

Debian§

Fedora§

RHEL and derivatives§

Ubuntu§

macOS§

Node.js§

Startup and shutdown§

Community Repositories§

Docker Images§

Initial configuration§

Source Code§

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

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