How to Install ZapZap on Debian: A WhatsApp Desktop Client for Linux

WhatsApp has never shipped a Linux desktop application, which leaves Linux users with a browser tab that gets lost among thirty others, loses its notifications when the browser is minimised, and cannot handle more than one account at a time.

ZapZap fixes that. It is an unofficial WhatsApp desktop client built with Python, PyQt6 and QtWebEngine: WhatsApp Web wrapped in a real desktop window, with the native integration a browser tab cannot provide. Multiple account profiles with isolated sessions, a system tray icon, proper desktop notifications, light and dark theming, spell checking, and custom CSS or JavaScript injection if you want to reshape the interface.

ZapZap is not in the Debian archive. Upstream offers Flatpak, AppImage, Snap and a .deb from GitHub releases, and the last of those means checking a release page whenever you wonder if you are out of date.

The unofficial deb.griffo.io repository packages ZapZap for APT, so it installs like any other application and updates alongside the rest of your system.

Install the Latest ZapZap on Debian: The Short Version

If you only came for the commands, this adds the repository and installs the latest ZapZap .deb package on Debian:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install zapzap

The rest of this guide explains what each command does, how to verify the install, how to keep ZapZap up to date, and what to check when something goes wrong.

What Makes ZapZap Special?

  • 🖥️ A real desktop application - Its own window, its own icon, its own place in the alt-tab order, rather than one tab among many.
  • 👥 Multiple accounts - Separate profiles with isolated web sessions, so work and personal numbers live side by side.
  • 🔔 Native notifications - Desktop notifications through your normal notification daemon, whether or not a browser is open.
  • 📥 System tray integration - Close to tray and keep receiving messages in the background.
  • 🎨 Light, dark and system themes - Follows your desktop theme, or pick one explicitly.
  • ✍️ Spell checking - Provided by QtWebEngine dictionaries.
  • 🎛️ Custom CSS and JavaScript - Injected globally or per account, for tweaks the web app does not offer.
  • 🆓 Open source - GPL-3.0, written in Python, easy to inspect.

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through APT, with no GitHub release page to watch.
  • Automatic dependency management for the PyQt6 and QtWebEngine packages ZapZap needs.
  • A native .deb rather than a Flatpak or Snap runtime, so it uses your system’s Qt stack.
  • Always tracks upstream releases so you stay close to the latest ZapZap.
  • Works across supported Debian releases, with the codename detected automatically.

Prerequisites

Before you start, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, Forky, or Sid)
  • A graphical desktop session; this is a GUI application
  • A phone with WhatsApp installed, to link the session by QR code
  • sudo privileges
  • curl installed (sudo apt install curl if needed)

Step 1: Add the deb.griffo.io Repository

Add the signing key and repository source:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

What each command does:

  1. Create the keyrings directory - ensures /etc/apt/keyrings exists with proper permissions.
  2. Install the GPG key - downloads the repository key and de-armours it into a dedicated keyring for verification.
  3. Add the repository - writes a signed-by source line, with lsb_release -sc supplying your Debian codename.
  4. Update the package list - refreshes APT so it knows about the new packages.

Step 2: Update the Package List

If you skipped the last line, run the update now:

sudo apt update

Step 3: Install ZapZap

Install ZapZap with APT:

sudo apt install zapzap

APT brings in python3-pyqt6, python3-pyqt6.qtwebengine, the Qt SVG bindings and the Qt Wayland platform plugin. QtWebEngine is a substantial download, so give it a moment on a slow connection.

Step 4: Verify the Installation

Launch ZapZap from your application menu, or from a terminal:

zapzap

The first run shows the familiar WhatsApp Web QR code. On your phone, open WhatsApp, go to Settings → Linked devices → Link a device, and scan it. Your chats sync down and the session persists, so you only do this once per profile.

Getting Started with ZapZap

The Tray and Background Behaviour

Closing the window sends ZapZap to the system tray rather than quitting, so messages and notifications keep arriving. Click the tray icon to bring it back, and quit properly from the tray menu when you actually want it gone.

On GNOME, tray icons need an AppIndicator shell extension to be visible at all; without one, ZapZap is still running, just invisible until you launch it again.

Multiple Accounts

Open the settings from within the application and add a second account. Each profile keeps its own isolated web session and its own QR-code link, so a work number and a personal number can be signed in at the same time and switched between from the sidebar.

Themes, Notifications and Downloads

The settings panel covers the parts a browser tab cannot:

  • Theme: light, dark, or follow the system.
  • Tray: whether closing the window hides to tray, and which icon style to use.
  • Notifications: native desktop notifications, with per-account control.
  • Downloads: where files land, and whether to be asked each time.
  • Spell checking: pick the dictionaries QtWebEngine should use.

Custom CSS and JavaScript

ZapZap can inject your own CSS and JavaScript into the web view, globally or per account. It is the escape hatch for anything the web interface does not let you change, such as adjusting font sizes, widening the chat column, or hiding elements you never use.

Wayland Sessions

The desktop entry launches ZapZap with your session’s default Qt platform. If you are on Wayland and hit rendering or scaling oddities, the application accepts a flag to force the Wayland platform explicitly:

zapzap --wayland

Conversely, forcing XWayland is a useful comparison when debugging:

QT_QPA_PLATFORM=xcb zapzap

Keeping ZapZap Updated

Because ZapZap arrived via APT, updates come with the rest of the system:

sudo apt update && sudo apt upgrade

Whenever deb.griffo.io ships a newer ZapZap, apt upgrade installs it. Quit and relaunch the application afterwards so you are running the new version.

Other Tools from deb.griffo.io

The repository packages plenty more for a Linux desktop:

  • Ulauncher - a fuzzy application launcher, handy for opening ZapZap with a keystroke.
  • Ghostty - a fast, GPU-accelerated terminal emulator.
  • Zed - a high-performance code editor.
  • termusic - a terminal music player for the background.

Troubleshooting

GPG or Key Errors

If APT reports an unsigned repository or an invalid key, import it again:

curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Package Not Found

If APT cannot see the zapzap package:

  1. Re-run sudo apt update after adding the repository.
  2. Confirm your release is supported (Bookworm, Trixie, Forky, or Sid).
  3. Inspect the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

A Blank or Black Window

That is almost always QtWebEngine and graphics drivers disagreeing. Try software rendering to confirm:

QTWEBENGINE_CHROMIUM_FLAGS="--disable-gpu" zapzap

If that works, the fix belongs in your graphics driver setup rather than in ZapZap. Running under XWayland with QT_QPA_PLATFORM=xcb zapzap is another useful data point.

No Desktop Notifications

Check that notifications are enabled in ZapZap’s settings, and that WhatsApp Web itself has notification permission inside the app. A notification daemon must also be running, which is the case in any standard desktop session but not necessarily in a minimal window manager setup.

The Tray Icon Is Missing

Stock GNOME does not display tray icons without an AppIndicator extension. Install one from the GNOME Extensions site, or use a desktop environment such as KDE Plasma or XFCE where the tray works natively.

Also Installed as a Flatpak or Snap

Two copies can shadow each other in menus and fight over the same profile directory. Pick one:

flatpak uninstall com.rtosta.zapzap
sudo snap remove zapzap

Missing Qt Platform Plugin

If startup fails with an error about the wayland or xcb platform plugin, install the platform packages explicitly:

sudo apt install qt6-wayland qt6-qpa-plugins

Uninstalling

Remove ZapZap with:

sudo apt remove zapzap

To also drop the repository and key:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Your linked sessions and settings live in your home directory under ~/.config and ~/.local/share, so remove those too if you want a clean slate. Unlinking the device from your phone’s Linked devices screen is the tidy way to finish.

Conclusion

Until WhatsApp ships a real Linux client, a well-made wrapper is the next best thing, and ZapZap is a good one: multiple accounts, a tray icon that actually works, native notifications, and theming that respects your desktop, all built on the Qt stack your distribution already provides.

Installing it from deb.griffo.io on Debian resolves the PyQt6 and QtWebEngine dependencies in one command and keeps the application current with a plain apt upgrade, instead of a periodic trip to a release page.

Frequently Asked Questions

How do I install the latest ZapZap on Debian?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install zapzap. The repository tracks upstream ZapZap releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for ZapZap?

Yes. deb.griffo.io publishes ZapZap as a signed .deb for Debian. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update ZapZap to the latest version?

Run sudo apt update && sudo apt upgrade. Once ZapZap is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

How do I install ZapZap on Ubuntu?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Ubuntu specifics: How to install ZapZap on Ubuntu.

Which Debian releases are supported?

Bookworm 12, Trixie 13, Forky and Sid. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream ZapZap project. ZapZap is an unofficial client and is not affiliated with or endorsed by WhatsApp or Meta.