How to Install UniFi OS on Ubuntu

Installing UniFi OS Server on Ubuntu

This article details the end-to-end deployment of UniFi OS Server on Ubuntu. You can use this KB to install UniFi OS on a VPS or a VM on-prem. We will use Ubuntu 24.04.4 LTS, and the UniFi OS version to install will be 5.0.6.

Infrastructure Prerequisites

Prior to deployment, verify the target environment meets the following baseline specifications:

  • Operating System: Ubuntu 24.04.4 LTS (64-bit) ( you can use other versions, check compatible versions in the Ubiquiti documentation)
  • Compute: Minimum 2 vCPUs
  • Memory: Minimum 4 GB RAM
  • Storage: Minimum 40 GB available disk space
  • Privileges: root or sudo access required

Note: Docker is not supported. UniFi OS Server strictly utilizes Podman for container lifecycle management. All container operations execute under a dedicated system user (uosserver).

Pre-Deployment:

If you are migrating an existing deployment from the legacy UniFi Network Server application to the new UniFi OS Server, you must gracefully terminate the existing network service to prevent port binding conflicts.

bash
sudo systemctl stop unifi
sudo systemctl disable unifi

Installation Procedure

Phase 1: Container Runtime Initialization

UniFi OS Server relies on Podman and user-mode networking components. Refresh local repositories and install the required dependency chain.

bash
sudo apt-get update && sudo apt-get install -y podman uidmap slirp4netns iptables curl wget ca-certificates

Verify the Podman runtime version to ensure compatibility. UniFi OS Server requires Podman version 4.3.1 or higher.

bash
podman --version

Exception Handling for Outdated Repositories:
If the native Ubuntu repository returns a Podman version older than 4.3.1, import the Kubic repository to force a modern build:

bash
# Append the Kubic repository to APT sources
echo "deb https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/unstable/xUbuntu_24.04/ /" | sudo tee /etc/apt/sources.list.d/devel:kubic:libcontainers:unstable.list

# Import the corresponding GPG signature key
curl -fsSL https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/unstable/xUbuntu_24.04/Release.key | sudo tee /usr/share/keyrings/libcontainers-unstable.asc

# Update package index and enforce latest Podman installation
sudo apt-get update && sudo apt-get install -y podman

Phase 2: Package Acquisition

Create a dedicated staging directory for the installer payload.

bash
sudo mkdir -p /usr/local/src/unifi-os-server
cd /usr/local/src/unifi-os-server

Retrieve the current UniFi OS Server binary. Always verify the latest build via the Ubiquiti Releases portal and copy the explicit link address. You can get the links from here:

https://ui.com/download

bash
# Example syntax using curl for the 5.0.6  build
sudo curl -LO https://fw-download.ubnt.com/data/unifi-os-server/1856-linux-x64-5.0.6-33f4990f-6c68-4e72-9d9c-477496c22450.6-x64

Phase 3: Binary Execution and Container Provisioning

Modify the binary permissions to allow execution, then invoke the installer with elevated privileges.

bash
sudo chmod +x ./1856-linux-x64-5.0.6-33f4990f-6c68-4e72-9d9c-477496c22450.6-x64
sudo ./1856-linux-x64-5.0.6-33f4990f-6c68-4e72-9d9c-477496c22450.6-x64

During execution, the installer scaffolds the Podman container architecture and provisions the uosserver Linux system user to govern the container namespace.

Post-Installation & Configuration

Local Dashboard Access

Once the initialization routine completes, the local management interface binds to TCP port 11443. Navigate to:

https://<your-server-ip>:11443

Initial container spin-up and database generation may require several minutes before the Network application transitions to an available state.

Identity Management: Local Credentials vs. UI SSO

During the initial setup, you must define the authentication.

  1. Local Credentials: Establish a localized Super Admin account. This is strictly local to the server.
  2. UI SSO (Remote Management): Authenticate with a Ubiquiti UI Account to enable remote administration via UniFi Site Manager, among other features like automated backups, this is the recommended method.

Device adoption.

If your UniFi devices are in the same network as the Ubuntu VM/UniFi OS server, you should be able to adopt them directly. If these are in other networks, you will need to perform a layer 3 adoption. You can follow the steps from this KB:

https://www.unihosted.com/blog/how-to-set-inform-in-unifi-a-guide

Service Management & CLI Operations

The uosserver CLI commands.

The installation includes a dedicated CLI utility (uosserver) wrapping the underlying Podman commands.

bash
uosserver status

Common uosserver Arguments:

  • start / stop: Controls the active container lifecycle.
  • status: Outputs active states of the container and nested services.
  • shell: Spawns a TTY shell directly inside the UniFi OS container namespace.
  • support: Generates a localized .supp file for diagnostics.

To interact with Podman directly, impersonate the uosserver user:

bash
uosserver podman ps
uosserver podman logs unifi-os

Verifying the Deployment (Status Interpretation)

To verify the installation was successful and understand the running state of the architecture, run the status command:

bash
uosserver status

The output provides a top-to-bottom view of the UniFi OS stack:

  1. Container Layer (uosserver): The top line indicates if the Podman container is running. Look for Up ... (healthy).
  2. Host Services: Confirms the systemd service (uosserver.service) on the Ubuntu host is actively communicating with the container.
  3. Container Services (Nested): UniFi OS uses a nested systemd environment inside the container. You will see internal services like unifi-core (management OS), ulp-go (Identity), and unifi (Network App).

Troubleshooting Common Errors

If the installation fails or the dashboard is inaccessible, review these common pitfalls:

  • Port 11443 Conflicts: UniFi OS Server binds to TCP port 11443. Ensure no other local services (or legacy UniFi controllers) are occupying this port. Check your firewall (e.g., ufw) to ensure traffic is permitted.
  • Podman Version Mismatch: The installation will fail if the Ubuntu repository provides an outdated Podman version. Ensure you are running podman --version 4.3.1 or higher (refer to Phase 1 exception handling).
  • Clean Uninstall: If the installation is corrupted, use the built-in purge command to completely wipe the container, images, and networking bridges before retrying: uosserver uosserver-purge.

Summary

That’s it! You successfully installed UniFi OS, keep in mind that currently does not support UniFi Protect, Access, or Talk. Features and update paths may change rapidly.

When does Managed UniFi hosting make more sense?

Managing UniFi at scale introduces operational risk: inconsistent versions, manual backups, expiring certificates, and hardware failures. Many MSPs move to hosted UniFi controllers to centralize infrastructure while retaining full network control.