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

# Windows Installation

The NetBird client 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.

1. Download the latest Windows release:
    - <Button href="https://pkgs.netbird.io/windows/x64" variant="text">EXE Installer</Button><br />
    - <Button href="https://pkgs.netbird.io/windows/msi/x64" variant="text">MSI Installer</Button><br />
2. Execute the installer and proceed with the installation steps
3. This will install the UI client in the `C:\Program Files\NetBird` and add the daemon service
4. After installing, you can follow the steps from [Running NetBird with SSO Login](#running-net-bird-with-sso-login).
<Note>
    To uninstall the client and service, you can use Add/Remove programs
</Note>

## Silent and Automated Installation

Both installers support silent (unattended) installation for use with RMM tools, MDM platforms, and scripted deployments.

<Note>
    Silent installation writes to `C:\Program Files` and registers a Windows service, so it requires an elevated administrator or `SYSTEM` context. Make sure the deployment job runs elevated: tools such as PDQ, Intune, and Group Policy typically install as `SYSTEM` when targeting computers, but a job configured to run in the user's context is not elevated and fails with exit code `1625` (`This installation is forbidden by system policy`). A standard user running the installer interactively is prompted for elevation instead.
</Note>

### EXE Installer (NSIS)

Run the EXE installer with the `/S` flag for a silent installation:

```bash
netbird_installer_<VERSION>_windows_amd64.exe /S
```

The installer no longer writes a machine-wide `HKLM\Software\Microsoft\Windows\CurrentVersion\Run` entry. Starting with v0.75.0, the desktop app manages launch at login as a per-user preference.

### MSI Installer

Run the MSI installer with `msiexec` for a silent installation:

```bash
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet
```

The MSI does not expose an `AUTOSTART` property. On a fresh desktop installation, the app enables **Launch NetBird UI at Login** for the current user the first time the UI runs. Upgrades preserve the user's existing preference. Users can change it under **Settings → General**, and administrators can suppress or remove the per-user registration with the [`disableAutostart` MDM setting](/client/mdm-integration#disableAutostart).

<Note>
    **Launch NetBird UI at Login** affects only the graphical interface. The NetBird background service starts independently and can maintain connectivity even when the UI does not launch.
</Note>

### Combining with a Setup Key

For fully automated deployments where peers should register without user interaction, combine silent installation with a [setup key](/manage/peers/register-machines-using-setup-keys):

```bash
netbird_installer_<VERSION>_windows_amd64.exe /S
netbird up --setup-key <SETUP KEY>
```

Or with the MSI installer:

```bash
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet
netbird up --setup-key <SETUP KEY>
```

<Note>
    For MDM-specific deployment guides, see [Deploy with Intune](/manage/peers/mdm-deployment/intune-netbird-integration) or [Deploy with Acronis](/manage/for-partners/acronis-integration).
</Note>

## Updating an Existing Installation

There is no separate update package. The same installer upgrades an existing installation in place: run the newer version and it replaces the installed one, keeping the peer's registration and configuration under `C:\ProgramData\Netbird`. There is no need to re-run `netbird up` or pass a setup key again after an upgrade.

```bash
netbird_installer_<VERSION>_windows_amd64.exe /S
```

Or with the MSI installer:

```bash
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet /norestart /L*v netbird_upgrade.log
```

The `/L*v` log is optional but makes a failed silent upgrade far easier to diagnose.

Like the initial install, an upgrade requires an elevated context, so the upgrade job must run as administrator or `SYSTEM`. Two more things the upgrade job must get right:

- **Use the same installer type you deployed with.** Neither installer detects an installation made by the other, so switching from EXE to MSI (or back) produces a second, overlapping installation instead of an upgrade.
- **Use a job that runs the installer even when NetBird is already present.** Some install jobs deliberately skip machines where the application is already installed, and a job like that will never upgrade. The script in the [Group Policy deployment guide](/manage/peers/mdm-deployment/windows-gpo-deployment), for example, exits early if NetBird is already installed, so use an upgrade-capable job for updates.

<Note>
    The upgrade stops and restarts the NetBird service, so the peer briefly disconnects during the install. This also applies when you push the upgrade over the NetBird tunnel itself: the session drops mid-install and comes back once the service restarts.
</Note>

<Note>
    Alternatively, an administrator can enable [Automatic Updates](/manage/peers/auto-update) under **Settings &raquo; Clients** (requires v0.61.0 or later on the clients and, when self-hosting, on the Management server). Clients then prompt the user to install the configured version and the NetBird service performs the install, with no administrator rights required from the user; the **Force Automatic Updates** toggle (v0.67.0 or later, again on both the clients and the Management server) installs without prompting. If you deploy and hold a specific version with the installer while Automatic Updates is set to **Latest Version**, clients will be prompted, or with Force updated, past the version you are holding, so pin a **Custom Version** instead.
</Note>

The two installers treat downgrades differently:

- **The MSI refuses to downgrade.** Installing an MSI older than the installed version changes nothing and fails with *"A newer version of NetBird is already installed"*. In quiet mode `msiexec` exits with `1603`, but `1603` is Windows Installer's generic fatal-error code and also fires on unrelated failures, so confirm a suspected downgrade attempt in the `/L*v` log rather than from the exit code alone. To roll back an MSI installation, uninstall NetBird and then install the older MSI; the uninstall leaves the configuration under `C:\ProgramData\Netbird` in place, so the peer keeps its identity.
- **The EXE does not check versions.** It removes the existing EXE installation and installs the packaged version even when that version is older, so rolling back an EXE installation is just a normal silent run of the older installer.

## 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](/client/desktop-app) for the complete interface.

### 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)).

For all systems:
```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
netsh interface ip show config name="wt0"
```