Skip to content

Correct Linux desktop app requirements and drop libappindicator #888

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
mlsmaycon merged 1 commit into from
Jul 28, 2026
Merged

Correct Linux desktop app requirements and drop libappindicator #888

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
65 changes: 47 additions & 18 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 @@ -6,26 +6,42 @@ The NetBird client (agent) allows a peer to join a pre-existing NetBird deployme

## Desktop App Dependencies

The desktop app introduced in NetBird v0.75.0 renders its interface in a GTK 4 WebKit webview. Supported packages normally install these dependencies automatically. For manual or unsupported deployments, install the corresponding packages before launching the GUI.
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.

**Debian 12+ / Ubuntu 22.04+**
<Warning>
The desktop app requires **GTK 4.10 or newer** and **WebKitGTK 6.0**. On older GTK 4 releases the app starts but crashes as soon as it opens a file dialog, so install the `netbird` CLI only on those systems.
</Warning>

Minimum releases that satisfy both requirements:

| Distribution | Desktop app | CLI |
| --- | --- | --- |
| Ubuntu | 24.04 LTS and newer | any supported release |
| Debian | 13 (trixie) and newer | any supported release |
| 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 |

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+**

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

**Fedora / RHEL 10+**
**Fedora 43+ / RHEL 10+**

```bash
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.

<Note>
RHEL 9 includes GTK 4 but does not provide WebKitGTK 6.0, which the desktop app requires. RHEL 10 is supported after enabling [EPEL](https://docs.fedoraproject.org/en-US/epel/getting-started/), which provides the `webkitgtk6.0` package.
Linux `netbird-ui` packages are built for **x86_64** only. On arm64 and other architectures, use the `netbird` CLI.
</Note>

On other distributions, install the equivalent **GTK 4**, **WebKitGTK 6.0**, and **xdg-utils** packages from your package manager, many systems may already include some of all of these packages.

## Linux Install Script

```bash
Expand All @@ -51,11 +67,15 @@ curl -fsSL https://pkgs.netbird.io/install.sh | sh
```bash
# for CLI only
sudo apt-get install netbird
# for GUI package
sudo apt-get install netbird-ui
# 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/Amazon Linux 2 (RPM)
### RHEL 9 / Amazon Linux 2 (YUM)

<Note>
These releases do not provide GTK 4.10 or WebKitGTK 6.0, so the desktop app is not available. Install the CLI and manage NetBird with `netbird` commands.
</Note>

1. Add the repository:
```bash
Expand All @@ -71,13 +91,10 @@ EOF
```
2. Install the package
```bash
# for CLI only
sudo yum install netbird
# for GUI package
sudo yum install libappindicator-gtk3 libappindicator netbird-ui
```

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

1. Create the repository file:
```bash
Expand All @@ -102,10 +119,18 @@ EOF
```bash
# for CLI only
sudo dnf install netbird
# for GUI package
sudo dnf install libappindicator-gtk3 libappindicator netbird-ui
# 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:
```bash
sudo dnf install epel-release -y
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.
On some recent releases, the default behaviour for `libappindicator` was changed, so we need to install `gnome-shell-extension-appindicator` and enable it:

Amazon Linux 2023 does not provide GTK 4 or WebKitGTK 6.0, so install the CLI only there.
Comment thread
mlsmaycon marked this conversation as resolved.

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
Expand All @@ -132,8 +157,8 @@ EOF
```bash
# for CLI only
rpm-ostree install netbird
# for GUI package
rpm-ostree install netbird-ui
# for the desktop app
rpm-ostree install netbird-ui gtk4 webkitgtk6.0 xdg-utils
Comment thread
mlsmaycon marked this conversation as resolved.
# Don't forget to reboot to apply
```
4. Start the service
Expand Down Expand Up @@ -239,6 +264,10 @@ reboot
zypper in netbird
```

<Note>
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>
Comment thread
mlsmaycon marked this conversation as resolved.

### NixOS 22.11+/unstable

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