Linux Installation

The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and self-hosted options available.

Desktop App Dependencies

The desktop app introduced in NetBird v0.75.0 renders its interface in a GTK 4 WebKit webview. The netbird-ui package does not declare these libraries as dependencies, so install them alongside it.

Minimum releases that satisfy both requirements:

Ubuntu 22.04 (GTK 4.6) and Debian 12 (GTK 4.8) ship WebKitGTK 6.0 but their GTK 4 is below 4.10, so the desktop app is not supported there. RHEL 9 provides neither GTK 4.10 nor WebKitGTK 6.0.

Debian 13+ / Ubuntu 24.04+

sudo apt-get install libgtk-4-1 libwebkitgtk-6.0-4 xdg-utils

Fedora 43+ / RHEL 10+

sudo dnf install gtk4 webkitgtk6.0 xdg-utils

On other distributions, install the equivalent GTK 4 (4.10+), WebKitGTK 6.0, and xdg-utils packages from your package manager. Many desktop systems already include some or all of them.

Linux Install Script

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Ubuntu/Debian (APT)

1. Add the repository:

 sudo apt-get update
 sudo apt-get install ca-certificates curl gnupg -y
 curl -sSL https://pkgs.netbird.io/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/netbird-archive-keyring.gpg
 echo 'deb [signed-by=/usr/share/keyrings/netbird-archive-keyring.gpg] https://pkgs.netbird.io/debian stable main' | sudo tee /etc/apt/sources.list.d/netbird.list

2. Update APT's cache

 sudo apt-get update

3. Install the package

 # for CLI only
 sudo apt-get install netbird
 # for the desktop app (Ubuntu 24.04+ / Debian 13+)
 sudo apt-get install netbird-ui libgtk-4-1 libwebkitgtk-6.0-4 xdg-utils

RHEL 9 / Amazon Linux 2 (YUM)

1. Add the repository:

sudo tee /etc/yum.repos.d/netbird.repo <<EOF
[netbird]
name=netbird
baseurl=https://pkgs.netbird.io/yum/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.netbird.io/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF

2. Install the package

 sudo yum install netbird

Fedora / RHEL 10+ / Amazon Linux 2023 (DNF)

1. Create the repository file:

sudo tee /etc/yum.repos.d/netbird.repo <<EOF
[netbird]
name=netbird
baseurl=https://pkgs.netbird.io/yum/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.netbird.io/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF

2. Import the file

#Fedora 40 or earlier/Amazon Linux 2023** (DNF 4)
 sudo dnf config-manager --add-repo /etc/yum.repos.d/netbird.repo
#Fedora 41 or later (DNF 5)
 sudo dnf config-manager addrepo --from-repofile=/etc/yum.repos.d/netbird.repo

3. Install the package

 # for CLI only
 sudo dnf install netbird
 # for the desktop app (Fedora 43+ / RHEL 10+)
 sudo dnf install netbird-ui gtk4 webkitgtk6.0 xdg-utils

On RHEL, AlmaLinux and Rocky Linux 10, webkitgtk6.0 comes from EPEL, so enable it before installing the desktop app:

 sudo dnf install epel-release -y

Amazon Linux 2023 does not provide GTK 4 or WebKitGTK 6.0, so install the CLI only there.

The tray icon uses the D-Bus StatusNotifierItem protocol. GNOME does not support it natively, so on GNOME desktops install gnome-shell-extension-appindicator and enable it:

sudo dnf install gnome-shell-extension-appindicator
sudo gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com

Under X11, you may need to restart GNOME Shell (Alt+F2, r, ⏎) after that. Under Wayland you need to logout and login again.

Fedora Silverblue (Atomic) / Universal Blue (rpm-ostree)

1. Create the repository file:

sudo tee /etc/yum.repos.d/netbird.repo <<EOF
[netbird]
name=netbird
baseurl=https://pkgs.netbird.io/yum/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.netbird.io/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF

3. Install the package

 # for CLI only
 rpm-ostree install netbird
 # for the desktop app
 rpm-ostree install netbird-ui gtk4 webkitgtk6.0 xdg-utils
 # Don't forget to reboot to apply

4. Start the service

systemctl enable --now netbird

Fedora Silverblue / Universal Blue / SteamOS / Immutable Distros (Homebrew)

1. If NetBird was previously installed with Homebrew, you will need to run:

# Stop and uninstall daemon service:
sudo netbird service stop
sudo netbird service uninstall
# unlink the app
brew unlink netbird

NetBird will copy any existing configuration from the NetBird's default configuration paths to the new default location.

2. Install Netbird

brew install netbirdio/tap/netbird

brew install llvm

3. Install and start the client daemon service:

  sudo /home/linuxbrew/.linuxbrew/bin/netbird service install
  sudo /home/linuxbrew/.linuxbrew/bin/netbird service start

You may need to adjust this command if you are not using the default /home/linuxbrew/.linuxbrew prefix for your Homebrew install.

sudo semanage fcontext -a -t bin_t \
  '/home/linuxbrew/\.linuxbrew/Cellar/netbird/[^/]+/bin/netbird'
sudo restorecon -Rv /home/linuxbrew/.linuxbrew/Cellar/netbird
sudo systemctl restart netbird

sudo systemctl status netbird

Fedora Silverblue / Universal Blue / SteamOS / Immutable Distros (Distrobox)

1. Create a distrobox container

distrobox create netbird --init --image debian:13 -a "--cap-add=NET_ADMIN" --additional-packages systemd --root

2. Install inside the container

distrobox enter --root netbird
curl -fsSL https://pkgs.netbird.io/install.sh | sh

3. Export the Netbird binary to the host

#from inside the container
distrobox-export -b /usr/bin/netbird

openSUSE (zypper)

1. Add the repository:

sudo zypper addrepo https://pkgs.netbird.io/yum/ netbird

2. Install the package / GPG key

• Key Fingerprint: AA9C 09AA 9DEA 2F58 112B 40DF DFFE AB2F D267 A61F
• Key ID: DFFEAB2FD267A61F
• Email: dev@netbird.io

# MicroOS (immutable OS with selinux)
transactional-update pkg in netbird
reboot

# Tumbleweed / Leap
zypper in netbird

NixOS 22.11+/unstable

1. Edit your configuration.nix

 { config, pkgs, ... }:
 {
   services.netbird.enable = true; # for netbird service & CLI
   environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
 }

2. Build and apply new configuration

 sudo nixos-rebuild switch

Binary Install

Installation from binary (CLI only)

1. Checkout NetBird releases
2. Download the latest release:

  curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz

3. Decompress

  tar xzf ./netbird_<VERSION>.tar.gz
  sudo mv netbird /usr/bin/netbird
  sudo chown root:root /usr/bin/netbird
  sudo chmod +x /usr/bin/netbird

After that you may need to add /usr/bin in your PATH environment variable:

  export PATH=$PATH:/usr/bin

4. Install and run the service

  sudo netbird service install
  sudo netbird service start

Updating

If your NetBird client was installed through a package manager, use that to update. If you used the one-command script to install, you can follow this to update:

netbird down
curl -fsSLO https://pkgs.netbird.io/install.sh
chmod +x install.sh
./install.sh --update
netbird up

Running NetBird with SSO Login

Desktop UI Application

Launch the desktop app and click Connect in the main window or system-tray menu. On first launch, choose NetBird Cloud or enter the URL of your self-hosted deployment. NetBird opens your browser to authenticate the device. See the desktop app guide for the complete interface.

CLI

Alternatively, you could use command line. Simply run

netbird up

It will open your browser, and you will be prompt for email and password. Follow the instructions.

Check connection status:

  netbird status

Running NetBird with a Setup Key

In case you are activating a server peer, you can use a setup key as described in the steps below.

This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.

For unattended deployments across many machines, pre-populate the client config so each peer registers on first start. See Bootstrap peers via config file.

1. Login to the Management Service. You need to have a setup key in hand (see setup keys).

  netbird up --setup-key <SETUP KEY>

Alternatively, if you are hosting your own Management Service provide --management-url property pointing to your Management Service:

  netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073

You could also omit the --setup-key property. In this case, the tool will prompt for the key.

2. Check connection status:

  netbird status

3. Check your IP:

  ip addr show wt0