Skip to content

Add community package installation instructions for Linux #918

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TechHutTV merged 2 commits into from
Aug 14, 2026
Merged

Add community package installation instructions for Linux #918

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
054cfd9
New Community Packages Section of Linux Install Docs
PizzaLovingNerd Aug 11, 2026
661ab7d
Change Community Package Disclaimer to <Warning>
PizzaLovingNerd Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 138 additions & 38 deletions src/pages/get-started/install/linux.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@ Minimum releases that satisfy both requirements:
| Fedora | 43 and newer | any supported release |
| RHEL / AlmaLinux / Rocky | 10 and newer, with [EPEL](https://docs.fedoraproject.org/en-US/epel/getting-started/) | any supported release |
| Amazon Linux | not available | 2 and 2023 |
| Alpine Linux | 3.23 and newer | 3.23 and newer |

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.

Expand Down Expand Up @@ -132,32 +131,13 @@ On RHEL, AlmaLinux and Rocky Linux 10, `webkitgtk6.0` comes from EPEL, so enable
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:
```bash
```
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.


### Alpine Linux - Requires community repository to be added to apk configuration
#### For CLI only:
```bash
apk add netbird netbird-openrc
rc-service netbird start
netbird up
rc-update add netbird default
```

#### for CLI and desktop app:
```bash
apk add netbird netbird-ui netbird-openrc
rc-service netbird start
netbird up
rc-update add netbird default
```

#### NetBird updates then just work with normal Alpine package management `apk update && apk upgrade`

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

1. Create the repository file:
Expand Down Expand Up @@ -288,23 +268,6 @@ zypper in netbird
These commands install the CLI. To use the desktop app, install `netbird-ui` together with your distribution's GTK 4.10+ and WebKitGTK 6.0 packages; openSUSE names them differently from Debian and Fedora, so check with `zypper search webkitgtk`.
</Note>

### NixOS 22.11+/unstable

1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)

```nix
{ config, pkgs, ... }:
{
services.netbird.enable = true; # for netbird service & CLI
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
}
```
2. Build and apply new configuration

```bash
sudo nixos-rebuild switch
```

### Binary Install
**Installation from binary (CLI only)**

Expand Down Expand Up @@ -341,6 +304,143 @@ After that you may need to add /usr/bin in your PATH environment variable:
sudo netbird service start
```

## Community packages

<Warning>
The packages in this section are maintained by Linux distributions and other community package repositories. NetBird does not build or publish them. Available versions, architectures, service integration, and desktop app support may differ from the officially supported NetBird packages above.
</Warning>

Your distribution's normal update process will update NetBird when a newer package becomes available.

### Alpine Linux (APK)

The `netbird` package is available in the [Alpine Community repository](https://pkgs.alpinelinux.org/packages?name=netbird). Make sure the Community repository is enabled, then install the client and its OpenRC service as the root user:

```bash
apk update
apk add netbird netbird-openrc
Comment thread
coderabbitai[bot] marked this conversation as resolved.
```

To install the desktop app as well:

```bash
apk add netbird-ui
```

Enable and start the service:

```bash
rc-update add netbird default
rc-service netbird start
```

### ALT Linux Sisyphus (APT-RPM)

NetBird is available in the [ALT Linux Sisyphus repository](https://packages.altlinux.org/en/sisyphus/srpms/netbird/):

```bash
sudo apt-get update
sudo apt-get install netbird
sudo systemctl enable --now netbird
```

### Arch Linux

#### Arch User Repository (AUR)

The Arch User Repository (AUR) is a community-driven repository of package build scripts. Packages are user-produced content and are not vetted by the Arch Linux team.

The AUR provides [`netbird`](https://aur.archlinux.org/packages/netbird), which builds the client from source, and [`netbird-bin`](https://aur.archlinux.org/packages/netbird-bin), which installs the prebuilt release binary. Review the `PKGBUILD`, then build your preferred package as a regular user. For example, to build `netbird`:

```bash
git clone https://aur.archlinux.org/netbird.git
cd netbird
makepkg -si
```

The desktop app is available as [`netbird-ui-bin`](https://aur.archlinux.org/packages/netbird-ui-bin):

```bash
git clone https://aur.archlinux.org/netbird-ui-bin.git
cd netbird-ui-bin
makepkg -si
```

You can also install these packages with an [AUR helper](https://wiki.archlinux.org/title/AUR_helpers) that you already use.

#### Chaotic-AUR

Chaotic-AUR provides prebuilt packages from the AUR. If you already have [Chaotic-AUR](https://aur.chaotic.cx/docs) configured, install its prebuilt `netbird` package with Pacman:

```bash
sudo pacman -Syu netbird
```

After installing either AUR package or the Chaotic-AUR package, enable and start the default NetBird client instance:

```bash
sudo systemctl enable --now netbird@main.service
```

### NixOS 22.11+/unstable

1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config):

```nix
{ config, pkgs, ... }:
{
services.netbird.enable = true; # NetBird service and CLI
environment.systemPackages = [ pkgs.netbird-ui ]; # Desktop app
}
```

2. Build and apply the new configuration:

```bash
sudo nixos-rebuild switch
```

### openSUSE Tumbleweed (Zypper)

The `netbird` package is available from the [openSUSE Tumbleweed OSS repository](https://software.opensuse.org/package/netbird):

```bash
sudo zypper refresh
sudo zypper install netbird
sudo systemctl enable --now netbird
```

This package is separate from the NetBird-hosted RPM repository described earlier on this page.

### Solus Polaris (eopkg)

The official [Solus package recipe](https://github.com/getsolus/packages/tree/main/packages/n/netbird) provides `netbird` and `netbird-ui`, and both packages are available in Polaris ([package listings](https://pkgs.org/search/?q=netbird)). Refresh the repository and update the system before installing the client:

```bash
sudo eopkg update-repo
sudo eopkg upgrade
sudo eopkg install netbird
sudo systemctl enable --now netbird.service
```

To install the desktop app as well:

```bash
sudo eopkg install netbird-ui
```

The desktop package depends on the `netbird` client package, so eopkg installs the client automatically if it is not already present.

### Verify the service

After installing and starting a community package, check that the CLI can reach the daemon:

```bash
sudo netbird status
```

Before you log in, the command should return daemon status rather than a socket or connection error. Depending on the package version, it may report `Daemon status: NeedsLogin` or show `Management: Disconnected`. Continue with one of the login methods below. On Alpine, where these instructions are run as root, omit `sudo`.

## Updating

If your NetBird client was installed through a package manager, use that to update.
Expand Down
Loading