https://github.com/rafatosta/zapzap
WhatsApp desktop application written in PyQt6 + PyQt6-WebEngine.
https://github.com/rafatosta/zapzap
flathub flatpak linux linux-desktop messaging pyqt6 python qt qt6 whatsapp whatsapp-web
Last synced: 7 days ago
JSON representation
WhatsApp desktop application written in PyQt6 + PyQt6-WebEngine.
- Host: GitHub
- URL: https://github.com/rafatosta/zapzap
- Owner: rafatosta
- License: gpl-3.0
- Created: 2022-01-01T14:34:09.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2026-05-23T21:27:34.000Z (11 days ago)
- Last Synced: 2026-05-23T22:20:17.354Z (10 days ago)
- Topics: flathub, flatpak, linux, linux-desktop, messaging, pyqt6, python, qt, qt6, whatsapp, whatsapp-web
- Language: Python
- Homepage: http://rtosta.com/zapzap/
- Size: 11.9 MB
- Stars: 1,031
- Watchers: 2
- Forks: 67
- Open Issues: 42
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# [ZapZap](https://rtosta.com/zapzap-web/) – WhatsApp Desktop for Linux & Windows
## 📌 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)](https://en.wikipedia.org/wiki/Progressive_web_app), built with **PyQt6 + PyQt6-WebEngine**.
📌 Technical documentation:
See [docs/technical-documentation.md](docs/technical-documentation.md)
---
## 📥 Download
- **[Flathub](https://flathub.org/apps/details/com.rtosta.zapzap)**
- **[AppImage](https://github.com/rafatosta/zapzap/releases/latest/download/ZapZap-x86_64.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
- **Account Grid View** (Quickly switch between all accounts)
- 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**
- **Native Windows support** (SQLite + Registry settings)
### 🧩 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//css`
- `customizations/accounts//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:
```bash
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`:
``` bash
sudo dnf install -y dbus-devel pkg-config gcc python3-devel
```
Then:
``` bash
pip install -r requirements.txt
```
# 🚀 Running ZapZap
``` bash
python run.py [dev|preview|build] [options]
```
## 🔧 Development Mode
Without translations:
``` bash
python run.py dev
```
With translations:
``` bash
python run.py dev --build-translations
```
#### Debugging WebEngine
- Open DevTools for current account page: `View -> Open DevTools` (`Ctrl+Shift+I`)
## 👀 Preview Mode
Flatpak:
``` bash
python run.py preview --flatpak
```
AppImage:
``` bash
python run.py preview --appimage
```
Windows:
``` bash
python run.py preview --windows
```
With translations:
``` bash
python run.py preview --build-translations --flatpak
```
## 📦 Build AppImage
``` bash
python run.py build --appimage
```
Example:
``` bash
python run.py build --appimage 6.0
```
## 📦 Build Flatpak Onefile
``` bash
python run.py build --flatpak-onefile
```
Output:
dist/com.rtosta.zapzap.flatpak
### 📦 Build Windows (EXE)
``` bash
python run.py build --windows
```
Output:
dist/ZapZap.exe
dist/ZapZap-Windows.zip
## 📦 Install as Python Module
``` bash
pip install .
```
### Uninstall
``` bash
pip uninstall zapzap
```
## 🔧 uv Tool
``` bash
uv tool install . --with-requirements requirements.txt
```
## 📦 Packaging
- **[Flatpak](https://github.com/flathub/com.rtosta.zapzap)**
- **[AppImage](_scripts/build-appimage.sh)**
## 🌍 Translation
ZapZap supports translations. If your language file is missing from the [po](/po) folder, submit a pull request or open an [issue](https://github.com/rafatosta/zapzap/issues).
## 🤝 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](https://www.paypal.com/donate/?business=E7R4BVR45GRC2&no_recurring=0&item_name=ZapZap+-+Whatsapp+Desktop+for+linux%0AAn+unofficial+WhatsApp+desktop+application+written+in+Pyqt6+%2B+PyQt6-WebEngine.¤cy_code=USD)
**Pix:** [Donate via Pix](https://nubank.com.br/pagar/3c3r2/LS2hiJJKzv)
**Ko-fi:** [Donate via Ko-fi](https://ko-fi.com/X8X2E1OLG)
## 📬 Contact
**Maintainer:** Rafael Tosta
**Email:** [rafa.ecomp@gmail.com](mailto:rafa.ecomp@gmail.com)