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

There is no official WhatsApp application for Linux. What Linux users get instead is web.whatsapp.com in a browser tab: easy to lose among the others, quiet when the browser is minimised, and limited to one account at a time.

ZapZap is the unofficial desktop client that closes the gap. Built with Python, PyQt6 and QtWebEngine, it wraps WhatsApp Web in a proper application window and adds the native integration a tab cannot offer: multiple account profiles with isolated sessions, a system tray icon, real desktop notifications, light and dark theming, spell checking, and custom CSS or JavaScript injection when you want to adjust the interface.

ZapZap is not in the Ubuntu archive. Upstream publishes Flatpak, Snap, AppImage and a .deb on GitHub releases; the .deb route works fine but leaves updates entirely up to you.

The unofficial deb.griffo.io repository packages ZapZap for APT, so it installs like any other application and upgrades with the rest of the system, using your distribution’s Qt libraries rather than a bundled runtime.

Install the Latest ZapZap on Ubuntu: The Short Version

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

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, icon and place in the alt-tab order instead of one tab among thirty.
  • 👥 Multiple accounts - Isolated profiles and sessions, so a work number and a personal number can both be signed in.
  • 🔔 Native notifications - Delivered by your normal notification daemon, browser or no browser.
  • 📥 System tray integration - Close to tray and keep receiving messages in the background.
  • 🎨 Light, dark and system themes - Match your desktop or choose explicitly.
  • ✍️ Spell checking - Through QtWebEngine dictionaries.
  • 🎛️ Custom CSS and JavaScript - Applied globally or per account for interface tweaks.
  • 🆓 Open source - GPL-3.0, written in Python, straightforward to audit.

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through APT rather than a release page you have to remember.
  • Automatic dependency management for PyQt6 and QtWebEngine.
  • A native .deb using the system Qt stack, with no Snap or Flatpak runtime in between.
  • Always tracks upstream releases so you stay close to the latest ZapZap.
  • Works across supported Ubuntu releases, with the codename detected for you.

Prerequisites

Before starting, confirm you have:

  • An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
  • 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

Register the 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

Breaking it down:

  1. Create the keyrings directory - makes sure /etc/apt/keyrings exists with the right permissions.
  2. Install the GPG key - downloads and de-armours the repository key into its own keyring so APT can verify signatures.
  3. Add the repository - writes a signed-by source line, letting lsb_release -sc fill in your Ubuntu codename.
  4. Update the package list - refreshes APT’s view of available packages.

Step 2: Update the Package List

If you did not run the final command above, do it now:

sudo apt update

Step 3: Install ZapZap

Install with APT:

sudo apt install zapzap

APT pulls in python3-pyqt6, python3-pyqt6.qtwebengine, the Qt SVG bindings and the Qt Wayland platform plugin. QtWebEngine is a large download, so allow a little time.

Step 4: Verify the Installation

Start ZapZap from the Activities overview, or from a terminal:

zapzap

The first launch shows the WhatsApp Web QR code. On your phone, open WhatsApp and go to Settings → Linked devices → Link a device, then scan it. The session persists after that, so this is a one-time step per profile.

Getting Started with ZapZap

The Tray and Background Behaviour

Closing the window hides ZapZap to the tray instead of exiting, so messages and notifications keep coming. Click the tray icon to restore it, and use the tray menu to quit for real.

Stock Ubuntu GNOME shows AppIndicator tray icons out of the box, so this works without extra setup on a default install.

Multiple Accounts

Add a second account from the settings panel. Each profile gets its own isolated session and its own device link, so you can stay signed in to two numbers at once and switch between them in the sidebar.

Themes, Notifications and Downloads

The settings cover everything a browser tab cannot:

  • Theme: light, dark, or follow the system.
  • Tray: hide-to-tray behaviour and icon style.
  • Notifications: native desktop notifications, controllable per account.
  • Downloads: default folder, and whether to prompt each time.
  • Spell checking: which QtWebEngine dictionaries to load.

Custom CSS and JavaScript

ZapZap can inject your own CSS and JavaScript into the web view, globally or per account. That covers anything WhatsApp Web will not let you change: font sizes, a wider chat column, hiding interface elements you never touch.

Wayland Sessions

Ubuntu defaults to a Wayland session on recent releases. ZapZap uses the session’s Qt platform by default, and can be told explicitly:

# Force the Wayland platform
zapzap --wayland

# Force XWayland, useful when comparing behaviour
QT_QPA_PLATFORM=xcb zapzap

If you see scaling or rendering oddities, trying both is the fastest way to narrow the cause.

Keeping ZapZap Updated

ZapZap upgrades with the rest of Ubuntu:

sudo apt update && sudo apt upgrade

When deb.griffo.io publishes a newer ZapZap, apt upgrade installs it. Quit and relaunch afterwards so the running instance is the new build.

Other Tools from deb.griffo.io

The repository has plenty more for a Linux desktop:

  • Ulauncher - a fuzzy application launcher 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 flags the repository as unsigned or the key as invalid, re-import it:

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 locate zapzap:

  1. Re-run sudo apt update after adding the repository.
  2. Verify your Ubuntu release is supported (Jammy, Noble, or newer).
  3. Check the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

A Blank or Black Window

Usually a disagreement between QtWebEngine and your graphics drivers. Confirm with software rendering:

QTWEBENGINE_CHROMIUM_FLAGS="--disable-gpu" zapzap

If that works, the problem is in the driver stack rather than ZapZap. QT_QPA_PLATFORM=xcb zapzap is another quick comparison.

No Desktop Notifications

Verify notifications are enabled in ZapZap’s settings and permitted inside WhatsApp Web itself. Also check Ubuntu’s Settings → Notifications, where an application can be muted globally without any sign of it in the app.

An Existing Snap or Flatpak Install

Ubuntu makes it easy to end up with the Snap as well. Two copies compete in the applications menu and can clash over profile data, so keep one:

sudo snap remove zapzap
flatpak uninstall com.rtosta.zapzap

Missing Qt Platform Plugin

If startup fails complaining about the wayland or xcb platform plugin:

sudo apt install qt6-wayland qt6-qpa-plugins

Uninstalling

Remove ZapZap with:

sudo apt remove zapzap

To also remove 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

Linked sessions and settings remain under ~/.config and ~/.local/share, so clear those for a fresh start. It is also worth unlinking the device from your phone’s Linked devices screen.

Conclusion

Until WhatsApp ships a native Linux client, a good wrapper is what is on offer, and ZapZap is a genuinely good one. Multiple accounts, a working tray icon, native notifications and theming that follows your desktop, all on the Qt libraries Ubuntu already ships.

Installing it from deb.griffo.io handles the PyQt6 and QtWebEngine dependency chain in a single command, and keeps the app current with the apt upgrade you already run.

Frequently Asked Questions

How do I install the latest ZapZap on Ubuntu?

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 Ubuntu. 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 Debian?

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

Which Ubuntu releases are supported?

Jammy 22.04 LTS, Noble 24.04 LTS and newer. 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.