netbird-docs/src/pages/get-started/install/linux.mdx

import {Note} from "@/components/mdx";

# 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](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.

## Desktop App Dependencies

<Note>
    This applies to the redesigned NetBird desktop app, currently available as a **release candidate** (download the latest from [pkgs.netbird.io](https://pkgs.netbird.io/releases/rc)). The current stable GUI does not require these packages.
</Note>

The redesigned desktop app renders its interface in a GTK 4 WebKit webview. Linux distributions package these libraries under inconsistent names, so install them manually before launching the GUI.

**Debian / Ubuntu**

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

On other distributions, install the equivalent **GTK 4**, **WebKitGTK 6.0**, and **xdg-utils** packages from your package manager.

## Linux Install Script

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

### Ubuntu/Debian (APT)
1. Add the repository:

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

```bash
 sudo apt-get update
```
3. Install the package

```bash
 # for CLI only
 sudo apt-get install netbird
 # for GUI package
 sudo apt-get install netbird-ui
```

### RHEL/Amazon Linux 2 (RPM)

1. Add the repository:
```bash
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
```bash
 # for CLI only
 sudo yum install netbird
 # for GUI package
 sudo yum install libappindicator-gtk3 libappindicator netbird-ui
```

### Fedora/Amazon Linux 2023 (DNF)

1. Create the repository file:
```bash
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
```bash
#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
```bash
 # for CLI only
 sudo dnf install netbird
 # for GUI package
 sudo dnf install libappindicator-gtk3 libappindicator netbird-ui
```
On some recent releases, the default behaviour for `libappindicator` was changed, so we need to 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:
```bash
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
```bash
 # for CLI only
 rpm-ostree install netbird
 # for GUI package
 rpm-ostree install netbird-ui
 # Don't forget to reboot to apply
```
4. Start the service
```bash
systemctl enable --now netbird
```

### Fedora Silverblue / Universal Blue / SteamOS / Immutable Distros (Homebrew)
<Note>
    Requires installation of [Homebrew](https://docs.brew.sh/Homebrew-on-Linux), Universal Blue images should have Homebrew preinstalled. 

    This method does not install the NetBird GUI. It installs the CLI only.
</Note>

1. If NetBird was previously installed with Homebrew, you will need to run:
```bash
# 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
```bash
brew install netbirdio/tap/netbird
```
<Note>
If it gives you an error saying to install Clang, you can install it with
```bash
brew install llvm
```
If that still doesn't work after that, try restarting your terminal to update the path.
</Note>
3. Install and start the client daemon service:
```bash
  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.

<Note>
On Fedora-based systems including Universal Blue, SELinux may block NetBird from running due to homebrew installing it in ~/linuxbrew.

You can fix this by running
```bash
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
```

If your Homebrew prefix is set to something other than /home/linuxbrew/.linuxbrew, you may need to adjust those commands to match.

You can verify that the NetBird service is running properly before and after making these changes by running:
```bash
sudo systemctl status netbird
```
</Note>

### Fedora Silverblue / Universal Blue / SteamOS / Immutable Distros (Distrobox)
<Note>
    Requires installation of [Distrobox](https://distrobox.it/), Universal Blue images should have Distrobox preinstalled.
</Note>
<Warning>
    You will also need to maintain and update Debian inside the Distrobox container.
</Warning>

1. Create a distrobox container
```bash
distrobox create netbird --init --image debian:13 -a "--cap-add=NET_ADMIN" --additional-packages systemd --root
```
2. Install inside the container
```bash
distrobox enter --root netbird
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
3. Export the Netbird binary to the host
```bash
#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`](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)**

1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
2. Download the latest release:
```bash
  curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
```

<Note>

    You need to replace some variables from the URL above:

    - Replace **VERSION** with the latest released version.
    - Replace **OS** with "linux", "darwin" for MacOS or "windows"
    - Replace **Arch** with your target system CPU architecture

</Note>

3. Decompress
```bash
  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:
````bash
  export PATH=$PATH:/usr/bin
````
4. Install and run the service
```bash
  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:

```bash
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
If you installed the Desktop UI client, you can launch it and click on Connect.
> It will open your browser, and you will be prompt for email and password. Follow the instructions.

<p>
    <img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>

### CLI
Alternatively, you could use command line. Simply run
   ```bash
  netbird up
   ```
> It will open your browser, and you will be prompt for email and password. Follow the instructions.

<p>
    <img src="/docs-static/img/get-started/netbird-sso-login-cmd.gif" alt="high-level-dia" className="imagewrapper-big"/>
</p>

Check connection status:
```bash
  netbird status
```

## Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/manage/peers/register-machines-using-setup-keys) 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](/manage/peers/bootstrap-via-config-file).

1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/manage/peers/register-machines-using-setup-keys)).

```bash
  netbird up --setup-key <SETUP KEY>
```

Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
```bash
  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:
```bash
  netbird status
```

3. Check your IP:

```bash
  ip addr show wt0
```