WhatsApp Desktop for Linux

An unofficial, personal-use native desktop client for WhatsApp Web on Linux.

🇧🇷 Leia em Português

---

⚠️ Legal Disclaimer

This is an unofficial, independent personal project, not affiliated with, endorsed by, or in any way connected to WhatsApp Inc., Meta Platforms, Inc., or any of their subsidiaries.

"WhatsApp", "WhatsApp Web", "Meta" and their logos and trademarks are the exclusive property of their respective owners. All rights reserved.

This project does not modify, reverse-engineer, redistribute, or replicate any WhatsApp software or service. It is simply a native Linux window wrapper that loads the official, publicly available WhatsApp Web application (web.whatsapp.com) — exactly as any web browser would. No WhatsApp code, assets, APIs, or proprietary data are included or redistributed.

This project was created solely for personal use, to fill a gap that exists on Linux, and is shared openly in case it helps others with the same need. Use it at your own risk.

If you are a representative of WhatsApp Inc. or Meta and have any concerns about this project, please open an issue and it will be addressed promptly.

---

Why this exists

WhatsApp ships a native app for Windows and macOS, but no official Linux desktop client. This project was built for personal use to have a proper, always-available native window — without keeping a browser tab open.

It wraps the official WhatsApp Web in an Electron window, adding Linux desktop integrations like system tray, multi-account support, notifications with conversation navigation, and more.

Features

• 💬 Multi-account — run Personal + Business (or any number) simultaneously, each in its own isolated window and session
• 🏷️ Emoji per account — assign a custom emoji to identify each account at a glance
• 🎨 Theme per account — Dark / Light / System, set independently for each account
• 📌 System tray — minimizes to tray on close; icon changes when there are unread messages
• 🔔 Notifications with navigation — click a notification to open the exact conversation
• 🔕 Do Not Disturb — silence all notifications manually or on a schedule (e.g. 22:00–07:00)
• 📥 Smart downloads — auto-saves files with WhatsApp-style names (WhatsApp Image 2025-01-01 at 10.30.00.jpg), remembers last folder
• 🎵 Floating audio mini-player — appears automatically when playing voice messages or audio
• 🚀 Start on login — opens minimized to tray at system startup
• 🔗 Deep linking — handles whatsapp://send?phone=... links
• 💾 Window persistence — saves size and position per account between sessions
• 🔍 Zoom control — Ctrl++ / Ctrl+- / Ctrl+0
• 📤 Export/Import settings — full backup and restore as JSON

Screenshots

Settings	Emoji picker per account

Login (QR Code)	Multi-account

Keyboard Shortcuts

Shortcut	Action
Ctrl+1, Ctrl+2, ...	Focus account 1, 2, ...
Ctrl+Q	Quit the application
Ctrl+W	Minimize window to tray
Ctrl+R / F5	Reload page
Ctrl++ / Ctrl+-	Zoom in / out
Ctrl+0	Reset zoom

Install

One-liner (recommended)

curl -fsSL https://github.com/cleyton1986/WhatsAppDesktop/releases/latest/download/install-online.sh | bash

Automatically detects your distro and installs the .deb (Debian/Ubuntu/Mint) or AppImage (other distros).

Manual — Debian / Ubuntu / Mint (.deb)

sudo dpkg -i whatsapp-desktop-cleyton_2.0.0_amd64.deb

Manual — Other distros (AppImage)

chmod +x whatsapp-desktop-cleyton-2.0.0.AppImage
./whatsapp-desktop-cleyton-2.0.0.AppImage

Download the latest release from the Releases page.

Build from source

Dependencies

• Node.js 18+
• Yarn

yarn install
yarn start        # development mode
yarn build        # build AppImage

How it works

┌──────────────────────────────────────────────────┐
│  whatsapp-desktop (Electron app)                  │
│  ├─ AccountWindow (one per account)               │
│  │   ├─ BrowserWindow ── web.whatsapp.com         │
│  │   ├─ Isolated session (persist:<id>)           │
│  │   └─ Smart download handler                    │
│  ├─ System tray (unread badge + per-account menu) │
│  ├─ Custom notification window (with navigation)  │
│  ├─ Floating audio mini-player                    │
│  └─ Config window (settings UI)                   │
└──────────────────────────────────────────────────┘

Tested on

Distribution	Desktop	Session	Status
Linux Mint 22.3	Cinnamon	X11	✅
Ubuntu 24.04	GNOME	X11	🟡
Other Debian-based	any	X11	🟡
Any distro	any	Wayland	🟡

✅ Confirmed working · 🟡 Expected to work, not tested

Tech stack

• Electron 33+
• TypeScript 5+
• electron-store — settings persistence
• electron-builder — AppImage packaging

Support the Project

If this project was useful to you and you'd like to support its development, consider buying me a coffee:

Any contribution is voluntary and greatly appreciated!

License

MIT — This license covers only the wrapper code in this repository.
WhatsApp, WhatsApp Web, and all related services remain the property of WhatsApp Inc. and Meta Platforms, Inc.