════════════════════════════════════════════════════════════════════════
  LINUX PACKAGES BY DISTRIBUTION
  Gnomad Desktop Assistant · docs/LINUX_PACKAGES.md
════════════════════════════════════════════════════════════════════════

LINUX PACKAGES BY DISTRIBUTION
==============================

Gnomad ships three official Linux formats from Tauri:

  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 (.deb, .rpm, AppImage) or the project site.

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  |  npm run pack:flatpak
  Snap (classic)  |  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.

────────────────────────────────────────

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.

════════════════════════════════════════════════════════════════════════
Built with ❤️ by Gnomad Studio 🦙
https://gnomadstudio.org
════════════════════════════════════════════════════════════════════════