Installation§

Warning

Official FreeUnit RPM/DEB packages are coming soon. As of April 2026, FreeUnit is distributed via Docker images, source builds, and pre-built unitctl binaries from GitHub Releases. The packages.nginx.org/unit/* repositories described below belong to the archived NGINX Unit project and will not receive further updates — use them only to migrate off. See the Migration guide for the current install paths and for maintainer instructions on rebasing community packages.

You can install FreeUnit in four alternative ways:

Choose from our official binary packages for a few popular systems (coming soon — see the migration guide for the current status and Docker / Source install paths).
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. Packagers updating those recipes should follow the maintainer guide.
Run our Docker official images, prepackaged with varied language combinations.
To fine-tune FreeUnit 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 the FreeUnit project. Use them with caution — they still ship the archived unit/ nginx-unit packages and may lag several releases behind.

Note

For package maintainers: the steps to rebase these recipes onto freeunitorg/freeunit (rename the package, swap the source URL, add provides/obsoletes aliases, refresh checksums) are documented in Community Repository Maintainers in the migration guide.

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§

FreeUnit images are published to GitHub Container Registry as multi-arch manifests (amd64 + arm64).

Tag format: VERSION-VARIANT (pinned) or latest-VARIANT (rolling).

Variant	Description
`minimal`	No language modules. Base for custom images.
`wasm`	WebAssembly Components (WASI 0.2) via Wasmtime.
`go1.24` `go1.25` `go1.26`	Go (single-version images).
`jsc17` `jsc21`	Java Servlet Container via Eclipse Temurin OpenJDK LTS. Runs `.war`/`.jsp` applications.
`node20` `node22` `node24`	Node.js (single-version images).
`perl5.38` `perl5.40`	Perl (single-version images).
`php8.3` `php8.4` `php8.5`	PHP (single-version images).
`python3.12` `python3.12-slim`	Python 3.12, full and slim variants.
`python3.13` `python3.13-slim`	Python 3.13, full and slim variants.
`python3.14` `python3.14-slim`	Python 3.14, full and slim variants.
`ruby3.3` `ruby3.4`	Ruby (single-version images).

To pull and run an image:

$ docker pull ghcr.io/freeunitorg/freeunit:TAG

$ docker run -d ghcr.io/freeunitorg/freeunit:TAG

Building custom language-version images

Clone the FreeUnit source, then build a specific variant locally:

$ git clone https://github.com/freeunitorg/freeunit
$ cd freeunit
$ docker build -f pkg/docker/Dockerfile.VARIANT pkg/docker/

See pkg/docker/ for all available Dockerfiles and the Makefile for the full build pipeline. For other customization scenarios, see the Docker howto.

Runtime details:

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

For full image details, see the GHCR package page 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 ghcr.io/freeunitorg/freeunit:1.35.4-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/  \
         ghcr.io/freeunitorg/freeunit:1.35.4-minimal

Source Code§

FreeUnit’s source code lives in the community-maintained fork at github.com/freeunitorg/freeunit.

Git

$ git clone https://github.com/freeunitorg/freeunit            # Latest updates to the repository

$ # -- or --

$ git clone -b 1.35.4 https://github.com/freeunitorg/freeunit  # Specific version tag; see https://github.com/freeunitorg/freeunit/tags

$ cd freeunit

Tarball

$ curl -LO https://github.com/freeunitorg/freeunit/archive/refs/tags/1.35.4.tar.gz

$ tar xzf 1.35.4.tar.gz

$ cd freeunit-1.35.4

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

v. 1.35.4

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