ZapZap – WhatsApp Desktop for Linux

📌 About

ZapZap brings the WhatsApp experience on Linux closer to that of a native application.
Since Meta does not provide a public API for third-party applications, ZapZap is developed as a Progressive Web Application (PWA), built with PyQt6 + PyQt6-WebEngine.

📌 About notifications and icons on Flatpak: See docs/notifications.md

📌 Technical documentation: See docs/technical-documentation.md

---

📥 Download

• Flathub
• AppImage

---

✨ Features

ZapZap extends WhatsApp Web with additional features:

🎨 Appearance

• Adaptive light and dark mode
• Fullscreen mode
• Custom window decorations
• Interface scaling adjustment (ideal for 2K/4K screens)

⚡ Usability

• Keyboard shortcuts for main options
• Adaptive system tray icon (notifies new messages)
• Background process support
• Drag-and-drop functionality
• Ability to select a custom folder for downloads
• Temporary folder for opening files

🛠️ Extras

• Spellchecker with language selection via context menu
• Customizable system tray icons
• Option to choose a folder for custom dictionaries
• Setting to disable the native file selection dialog (Hyprland)
• Custom CSS/JS with global + per-account override
• Reorganized Settings Panel
• Added Performance section

🧩 Customizations

• New Customizations page in Settings
• Supports Global customization and Current account customization
• Account mode supports inherit global settings + optional override
• Users can:
  • import .css and .js files
  • create and edit CSS/JavaScript files in dialogs
  • enable/disable each imported CSS/JS file independently
  • import CSS/JavaScript from any https:// URL
  • open customization folders directly
• Supports many userstyle files (.user.css) by extracting WhatsApp-targeted @-moz-document blocks
• Page actions: Save, Save and reload, Reload

Customization files are stored in the app local data path under:

• customizations/global/css
• customizations/global/js
• customizations/accounts/<id>/css
• customizations/accounts/<id>/js

Reserved for future extension support:

• customizations/extensions

---

⚠️ File upload notice

File uploads and filesystem permissions

To enable file uploads (documents, images, videos, audio, etc.) in WhatsApp Web, ZapZap requires access to the user’s folders.

This is due to technical limitations of QtWebEngine (Chromium) in modern environments such as Wayland and sandboxed applications (for example, Flatpak).
Under these conditions, the embedded browser cannot upload files correctly without direct access to the filesystem.

What this means in practice

• Without filesystem access:
  • file uploads may fail
  • files may be sent with no content
• With the required permissions granted:
  • file uploads work correctly
  • the experience matches that of a regular web browser

Recommended permissions

When running in a sandboxed environment (such as Flatpak), it is recommended to grant access to at least:

• Documents
• Videos
• Pictures
• Downloads

These permissions are used only to allow the user to select and upload files and are not used for automatic file scanning, indexing, or data collection.

Changing permissions on Flatpak

If ZapZap was installed via Flatpak, you can manage filesystem permissions using Flatseal (a graphical permission manager for Flatpak apps):

👉 https://flathub.org/apps/com.github.tchx84.Flatseal

Steps:

1. Install and open Flatseal
2. Select ZapZap from the application list
3. Enable access to the recommended folders (Documents, Videos, Pictures, Downloads)
4. Restart ZapZap

Optional terminal alternative:

flatpak override --user --filesystem=home com.rtosta.zapzap

After adjusting these permissions, file uploads, opening PDFs, and drag-and-drop should work normally.

⚙️ Development

Requirements

• Python 3.9 or higher

Fedora 43 System Dependencies

If pip install -r requirements.txt fails due to dbus-python:

sudo dnf install -y dbus-devel pkg-config gcc python3-devel

Then:

pip install -r requirements.txt

🚀 Running ZapZap

python run.py [dev|preview|build] [options]

🔧 Development Mode

Without translations:

python run.py dev

With translations:

python run.py dev --build-translations

Debugging WebEngine

• Open DevTools for current account page: View -> Open DevTools (Ctrl+Shift+I)

👀 Preview Mode

Flatpak:

python run.py preview --flatpak

AppImage:

python run.py preview --appimage

With translations:

python run.py preview --build-translations --flatpak 

📦 Build AppImage

python run.py build --appimage <version>

Example:

python run.py build --appimage 6.0

📦 Build Flatpak Onefile

python run.py build --flatpak-onefile

Output:

dist/com.rtosta.zapzap.flatpak

📦 Install as Python Module

pip install .

Uninstall

pip uninstall zapzap

🔧 uv Tool

uv tool install . --with-requirements requirements.txt

📦 Packaging

• Flatpak
• AppImage

🌍 Translation

ZapZap supports translations. If your language file is missing from the po folder, submit a pull request or open an issue.

🤝 Contributions

Contributions are welcome! Please submit a pull request with any improvements or changes you wish to propose.

📜 License

This project is licensed under the GPL. See the LICENSE file for more information.

💖 Donations

PayPal: Donate via PayPal

Pix: Donate via Pix

Ko-fi: Donate via Ko-fi

📬 Contact

Maintainer: Rafael Tosta

Email: rafa.ecomp@gmail.com