# Linux packages by distribution

Gnomad ships three official Linux formats from [Tauri](https://v2.tauri.app/distribute/):

| Format | File | Best for |
|--------|------|----------|
| **`.deb`** | `gnomad_*_amd64.deb` | Debian, Ubuntu, Linux Mint, Pop!\_OS, elementary, Zorin |
| **`.rpm`** | `gnomad-*-1.x86_64.rpm` | Fedora, RHEL, CentOS Stream, Rocky, AlmaLinux, openSUSE |
| **AppImage** | `gnomad_*_amd64.AppImage` | Arch, NixOS, Gentoo, or any distro without native packaging |

**Official downloads:** [GitHub Release v0.1.0-alpha](https://github.com/davidthegnomad/gnomad-desktop-assistant/releases/tag/v0.1.0-alpha) (`.deb`, `.rpm`, AppImage) or the [project site](https://davidthegnomad.github.io/gnomad-desktop-assistant/).

CI also builds on every push to `main` — backup artifacts under **Actions → Build**.

### Wayland vs X11

Gnomad detects `XDG_SESSION_TYPE` at runtime. On **Wayland**, use **left-click** on the tray icon to open the menu. Settings shows a hint when Wayland is detected. Optional context tools: `wl-paste` (Wayland), `xdotool`/`xclip` (X11).

Local build (on Ubuntu 22.04+ or Debian 12+):

```bash
npm run tauri:build:linux          # deb + rpm + AppImage
npm run tauri:build:linux:deb      # Debian/Ubuntu only
npm run tauri:build:linux:rpm      # Fedora/RHEL family only
npm run tauri:build:linux:appimage # universal binary only
```

Outputs:

- `src-tauri/target/release/bundle/deb/`
- `src-tauri/target/release/bundle/rpm/`
- `src-tauri/target/release/bundle/appimage/`

---

## Debian / Ubuntu / Mint / Pop!\_OS

```bash
sudo apt install ./gnomad_*_amd64.deb
```

Or:

```bash
sudo dpkg -i gnomad_*_amd64.deb
sudo apt-get install -f   # fix missing dependencies if needed
```

**Dependencies** (installed automatically): WebKitGTK 4.1, GTK 3, Ayatana or legacy app indicator (system tray).

**Remove:**

```bash
sudo apt remove gnomad
```

---

## Fedora / RHEL / Rocky / AlmaLinux

```bash
sudo dnf install ./gnomad-*-1.x86_64.rpm
```

**Dependencies:** `webkit2gtk4.1`, `gtk3`, `libappindicator-gtk3` (tray).

On Fedora 40+ you may need Ayatana instead of legacy indicator; if install fails, install tray support manually:

```bash
sudo dnf install libayatana-appindicator-gtk3
```

**Remove:**

```bash
sudo dnf remove gnomad
```

---

## openSUSE / SUSE

```bash
sudo zypper install ./gnomad-*-1.x86_64.rpm
```

Same RPM as Fedora family.

---

## Arch Linux / Manjaro

Tauri does not produce native `.pkg.tar.zst` bundles. Use the **AppImage**:

```bash
chmod +x gnomad_*_amd64.AppImage
./gnomad_*_amd64.AppImage
```

Optional: move to `~/Applications` or `/opt` and add a `.desktop` file.

For AUR maintainers, package the AppImage or release `.deb` via `debtap` — not maintained in this repo.

---

## Universal (AppImage)

Works on most glibc-based x86_64 distros without a package manager install step:

```bash
chmod +x gnomad_*_amd64.AppImage
./gnomad_*_amd64.AppImage
```

Integrate with the desktop (optional):

```bash
./gnomad_*_amd64.AppImage --appimage-extract
# or use AppImageLauncher / Gear Lever on some desktops
```

**Note:** Build on Ubuntu 22.04 / Debian 12 (or our CI) so glibc stays compatible with older systems. Building on Fedora-only may produce RPMs that won’t install on Debian and vice versa — that’s why we ship **both** `.deb` and `.rpm` plus AppImage.

---

## Snap / Flatpak

Optional community packaging (not in default CI release matrix):

| Format | Guide | Build |
|--------|-------|-------|
| **Flatpak** | [FLATPAK.md](FLATPAK.md) | `npm run pack:flatpak` |
| **Snap** (classic) | [SNAP.md](SNAP.md) | `npm run pack:snap` |

GitHub Actions: **Packaging** workflow (`workflow_dispatch`) for CI-built flatpak/snap artifacts.

For most users, prefer **deb**, **rpm**, or **AppImage** from [Releases](https://github.com/davidthegnomad/gnomad-desktop-assistant/releases).

---

## ARM64 (Raspberry Pi, ARM laptops)

Official CI artifacts include **x86_64** (Ubuntu 22.04) and **ARM64** (Ubuntu 24.04 ARM runner): `.deb` and `.AppImage` on both; `.rpm` on x86_64 only.

To cross-compile locally on a Debian/Ubuntu x86_64 host:

```bash
rustup target add aarch64-unknown-linux-gnu
sudo apt install gcc-aarch64-linux-gnu libwebkit2gtk-4.1-dev:arm64
export PKG_CONFIG_SYSROOT_DIR=/usr/aarch64-linux-gnu/
npm run tauri:build:linux:arm64
# or:
npm run tauri:build:linux -- --target aarch64-unknown-linux-gnu
```

AppImage cross-build for ARM is slower; prefer `.deb` on ARM boards running Debian/Ubuntu.

---

## Troubleshooting

| Issue | Fix |
|-------|-----|
| `GLIBC_2.xx not found` | Use CI-built packages or build on Ubuntu 22.04 / Debian 12 |
| Tray icon missing | Install `libayatana-appindicator3-1` (deb) or `libappindicator-gtk3` (rpm) |
| WebKit errors | `sudo apt install libwebkit2gtk-4.1-0` or `sudo dnf install webkit2gtk4.1` |
| RPM won’t install on Ubuntu | Use `.deb` or AppImage, not `.rpm` |

See also [`BUILD_PLATFORMS.md`](BUILD_PLATFORMS.md).