How to install and configure Unifi controller on Raspberry Pi?

install unifi controller on raspberry pi

If you have already managed multiple WiFi access points, you should know that this can be a nightmare …
But with good choices for hardware and a controller, this becomes easier
It’s the main goal of the Unifi controller: manage most of the tasks on a wireless network to avoid issues
And it’s available for Raspberry Pi so we like that 🙂

How to install and configure Unifi controller on Raspberry Pi?
The Unifi controller is available on all platforms: Windows, macOS and Linux (Debian)
And it’s possible to install it on your Raspberry Pi directly
Then you can use the web interface to configure access points and monitor wireless clients

The installation is straightforward, you can install it like any Debian package
But the access points configuration is not so easy and I saw no article explaining this
As I’m using it at work, I can show you all the configuration steps

Ubiquiti Networks products

Ubiquiti Networks introduction

Ubiquiti Networks is an American company, selling hardware for wireless technologies like access points, routers and cameras
They started with wireless devices and they are now diversifying upon a broader range of products
The latest innovative product concerns the solar technology, they help you to manage solar farms

Anyway, the product that interests us today is a software: Unifi controller
The goal of this product is to manage access points and wireless devices from an unique web interface
From the interface, you can see all the access points and broadcast an unique SSID
The controller will handle the roaming between access points and load distribution

Why do I need these products?

These products target mainly companies and large areas but you can have the same needs at home if you get issues with WiFi
If you need over one access point to cover all the house, it could be interesting to install these products at home

For example, let’s say you install three access points and the controller somewhere
You’ll have only one WiFi SSID in the all area
And you can move from one side to another without disconnection

Ubiquiti products

Ubiquiti products are distributed by resellers, but are also available on Amazon for example

To test these products, you don’t need a lot of things
Just buy one or more access points on Amazon and build your professional wireless network

Here is the link: Ubiquiti Unifi AP
You have several packages available: Only one, 2 AP, 4 AP, etc
Choose the one you prefer, but there is not a big saving by taking big packs, so you can try with one or two, and order the others after

If you have a POE Switch (this one for example), you can plug them only to the network cable
This will make the installation easier
If not, they provide an adapter with the AP (power cord + network = POE Network), but you need a power outlet and two RJ45 cables instead of only one cable for everything

Unifi controller installation

Now that you understand what are the Unifi products, we can move to the controller installation

Raspbian installation

As for any tutorial on this site, you must install Raspbian on your Raspberry Pi
Any version will do the job
If you don’t know how to do this, read my article on How to install Raspbian on your Raspberry Pi

Once installed, update it and reboot:

sudo apt update
sudo apt upgrade
sudo reboot

And enable SSH access:

sudo service ssh start

Set a static IP address

As our Raspberry Pi will be like a server on our network, we need to use:

  • A wired connection
    If you want a fast WiFi network, you need to have your controller and your access point on a good connection.
    So I don’t recommend setting up the controller with a WiFi connection
  • A static IP address
    The Raspberry Pi will become an important node on your network, so we need to fix its IP
    By default, the Raspberry Pi use the DHCP to get a random IP among those available

For the static IP, you can either fix the IP in the DHCP server (your Internet router probably), or set a static IP in the Raspberry Pi configuration

If you don’t know how to do this, I already explained it at the end of this article: Set a static IP address on your Raspberry Pi

Unifi controller installation

Now we are ready to start the installation
For these steps you have two choices

On the Ubiquiti downloads page you can find the Debian package to install the controller
You can download it and install it on your Raspberry Pi
But I don’t recommend it.

Because the Controller has a lot of updates, about every month you must download and install the new version
There is a repository available and it’s easier to manage all updates with apt rather than doing everything manually

  • Connect with SSH and switch to the root user
    sudo su
  • Add the repository in the apt configuration file
    echo 'deb unifi5 ubiquiti' >> /etc/apt/sources.list
  • Install dirmngr package to manage repository keys
    apt install dirmngr
  • Add the key
    apt-key adv --keyserver --recv C0A52C50

    This allow us to use software from the previous repository

  • Run apt update to update the available packages list
    apt update
  • And finally, install the Unifi package
    apt install unifi

    Answer yes and wait a few seconds for the installation process to finish

  • Reboot the Raspberry Pi to complete the installation

This is the end of the installation procedure, move on to the next part to know how to use it

Unifi controller configuration

First access

To access the web interface, go to https://<IP>:8443
You’ll get a browser warning because we don’t have a secured certificate for the moment
Accept the exception and move to the next page

When you access the interface for the first time, you need to choose a few parameters, like country and time zone
unifi controller wizard

Click “Next” once completed
Then the wizard asks you for devices to add
unifi controller devices wizard

Click next for the moment, we’ll see how to add devices on the controller later
On the next step, they ask you the WiFi configuration
unifi wifi configuration
Same thing, click on “Skip”. We’ll see that later in the full interface
And finally, you need to choose your user name and password to access the interface
unifi wizard user configuration
In the first part, enter your administrator user name, email and password
You’ll use these credentials to access the web interface
The device authentication is a different thing, it’s useful for managing access points

The final step is just a confirmation one. Click next if everything seems good
Then you’re asked to login with your cloud credentials:

It’s not mandatory, you can click on “Skip”

You are now ready to login in the web interface:
unifi controller login interface

Web interface overview

Once logged in the web interface, you’ll get a lot of sub menus to manage everything
For the moment, it should be pretty empty, but in the left bar you can see:

  • Dashboard: Here you can have a preview of your network performance (number of APs and clients)
    Most of this dashboard needs the Unifi Security Gateway, so it’s not an important page
  • Statistics: In this page you can monitor clients and traffic in the whole network
    For the moment, nothing here 🙂
  • Map: In this one you can upload a map of your building, and place all APs on it
    This way you can know where they are and see the global WiFi coverage (approximately)
  • Devices: This page shows you all the Unifi devices you have on your network
    It’s the most important page, you will manage APs from here
  • Clients: Same thing for the clients. You’ll see here all the connected clients with information about them (IP, AP, network usage, …)
  • Insights: Here you can see miscellaneous informations.
    I’m using this mainly to see known clients (not connected now, but you can check the history, block or unblock them)
  • Events: This window shows you all the recent logs on your network
    This can be clients connections, AP upgrades, roaming, …
  • Alerts: Same thing with errors and warnings
  • Settings: And this is the page where you’ll configure everything
    We’ll use it to create the wireless network
  • Chat support: If you need help from Unifi, you can ask for help here

Now that you have visited the whole interface, we can move forward to configure the access point

Add the first access point

Physical preparation

There are two possibilities for the access point cabling

With a POE switch:

  • Plug the access point to the POE Switch with an RJ45 cable
  • Basically, that’s it
    The status light should turn on and you can move to the next step

Without POE switch:

  • You must have a POE adapter like this:
    unifi poe adapter
    (it’s available on Amazon if you don’t have one with your access point: check it here)
  • Connect the LAN port to your switch or wall network socket
  • Connect the POE port to the access point
  • If the access point LED starts to blink, it’s ok

Software installation

Now that we powered on the access point, we can go back to the Unifi web interface for the next steps:

  • Access the web interface: https://IP:8443
  • Click on “Devices” in the left menu
  • You should now see your access point in the list:
    unifi ap pending adoption
    The controller is seeing it, but we need to tell that it’s an access point for this controller
  • Click on “Adopt” at the end of the line
    The adoption process starts, after a few seconds, you should get the “Connected” status
    unifi ap connected
  • If needed (probably), you can upgrade the AP firmware to the latest version by clicking “Upgrade”
    Your access point will take a few minutes to download and update the firmware
    unifi ap upgrade

Anyway, the first access point is ready and we can now create the wireless network (SSID)

You can click on the line to see and change other settings for the access point (on the right)
unifi ap properties

For example, you can set an alias for each access point to know which one is which
In the properties window, click on the config tab and set an alias
unifi set alias access pointunifi access point new name

Change everything you want on the access point and move to the SSID creation

Create your wireless network

Creating a wireless network is basically setting an SSID, a password and a security type
You can do this in the “Settings” menu from the left bar:

  • In settings, click on “Wireless Networks”
  • Then click on the “Create a new wireless network” button
    create new network
  • In the new window, choose an SSID, a security type and a password
    new wireless network creation
    Choose WPA-Personal for security, WEP is not secure
    And prefer a long password (ideally a phrase from 15 to 30 characters)
  • Click “Save”

The access points will restart with the new settings
After a few seconds the new wireless network is available for all your devices

unifi wifi windows

Connect to it and check that everything works fine
By default, the Unifi controller will give an IP address within your main network
You have nothing else to do, but you can change it in Settings > LAN

Then go back to the different menus to see information and statistics about your device
Enjoy 🙂

Related questions

Do I need to keep the Raspberry Pi on? Not really. As soon as the Raspberry Pi stops, the controller is no longer available but the access point continue to work. You can still access the WiFi network, but you lose controller’s features like roaming between APs

Do the Unifi controller have advanced features you don’t talk about? Yes, a lot. I made a quick tutorial, but you can do a lot more: schedule downtimes, create guest access with VLAN or not, Radius with Active Directory, filter MAC address, block and unblock clients, etc …

How to reset an Unifi access point? If you lose access to an access point or have strange scenarios in the adoption process, you can reset it to factory defaults. To do this, use the reset button near the RJ45 socket. While the access point is on, let the button pressed for 10 seconds and then wait for the reset.


That’s it, you know how to install and configure an Unifi controller on your Raspberry Pi
This controller is running perfectly on my Raspberry Pi 3B+
I don’t know how many clients it would handle, but at home it’s more than enough

If you have questions on this topic, leave me a comment and I’ll help you
I’m using this software at work for five years now, so I may have the answer 😉




  1. Ken Reply

    Configuration recommendations?

    I’ve found that iOS devices seem to have trouble connecting if not close to the AP. The result is incorrect password but the devices connect fine when close.

    Seems odd behavior for these enterprise APs.


  2. Jeff Reply

    I have yet to get this awesome (thanks for making it straight forward!) guide to work.. I realize it may be outdated and some dependencies or OS version may be effecting things. Would be great if someone could help update. Im still working at it.. (i have a working install of unifi but had to do it a very complicated way which made a mess out of the install).

    Ill post if i figure i out. Otherwise ill use my bloated install for now.

    • jeff Reply

      Edit.. Ok well 3rd time is the charm i guess.. I literally ran every command 3x.. and it finally worked when i did an apt update and it gave warnings on how unifi package has been configured multiple times…

      • JEFF Reply

        Main error preventing me was Signatures could not be verified as public key is not available. Request issues/else? Or does it override after so many attempts to NOKEY?

Leave a Reply

Your email address will not be published. Required fields are marked *