Zalo for Linux 🐧

An unofficial, community-driven port of the Zalo desktop application for Linux only, created by repackaging the official macOS client into a standard AppImage with integrated ZaDark.

Thanks realdtn2 for the solution: realdtn2/zalo-linux-2026.

⚠️ Important: Known Issues

• ✅ Fixed: Can't make or receive calls - The call module (zcall), which only ships as a macOS native binary, now runs under a Wine-based bridge (zcall-bridge). Voice calls, video calls (camera) and screen sharing work on Linux. The Full AppImage variants bundle Wine + GStreamer out of the box; the standard variants offer a one-click first-run setup. See zcall-bridge/README.md for details and system requirements.
• System/Auto Theme not working: The app does not follow the system's dark/light mode. Both ZaDark and Zalo ignore prefers-color-scheme. See issue #22.
• ✅ Fixed: Message Synchronization (E2EE) - Thanks to @realdtn2 for reimplementing db-cross-v4 with C++. E2EE message sync now works on Linux without any Wine workaround. Thanks to @DMKha2k7 for the PR. See PR #24 and issue #15.
• ✅ Fixed: No Photos/Videos, Files and Links on the Conversation Info panel - Caused by the missing db-cross-v4 module.
• ✅ Fixed: Can't see message reactions - Caused by the missing db-cross-v4 module.
• ✅ Fixed: Can't paste images from clipboard - Image files (.png, .jpg, .jpeg, …) can now be pasted into chats via Ctrl+V. Works on Wayland (wl-clipboard) and X11 (xclip). Thanks to @realdtn2 for the original solution and @DMKha2k7 for the PR. See PR #25 and issue #23.
• ✅ Fixed: Screenshot without/with Zalo window button - Uses native Linux screenshot tools (see issue #19). Supported tools: deepin-screen-recorder, spectacle, flameshot, gnome-screenshot, xfce4-screenshooter, mate-screenshot, ksnapshot, scrot. Thanks to @hthienloc for the solution.
• ✅ Fixed: No title bar with minimize/maximize/close buttons - Thanks to @NanKillBro for the solution. For more details, see issue #4
• ✅ Fixed: No tray menu icon
• ✅ Fixed: Freeze on login screen - Replaced macOS sqlite3 binaries with native Linux builds. See issue #13.

This project is best suited for users who need a native-feeling Zalo client on Linux and are comfortable with the technical workarounds required for full functionality.

🧩 Userscripts manager

Open Settings → Userscripts manager to create, paste, edit, import, delete, and enable or disable scripts that run inside Zalo. Tampermonkey-style metadata such as @name, @description, @version, @match, @include, and @exclude is recognized. Imported scripts may use the .js or .user.js extension.

The compatibility layer currently provides GM_info, GM_addStyle, GM_getValue, GM_setValue, GM_deleteValue, GM_listValues, and unsafeWindow. Changes take effect the next time the Zalo page is loaded.

Security: Userscripts execute with access to the current Zalo page and messages displayed in it. Only install scripts whose source you trust.

🌙 ZaDark Integration

This project includes integrated ZaDark, ZaDark is an extension that helps you enable Dark Mode, more privacy features, and additional functionality.

ZaDark helps you experience Zalo 🔒 more privately ✨ more personalized.

Features

• 🌙 Dark Mode optimized specifically for Zalo - Complete dark theme tailored for Zalo interface
• 🆃 Customize fonts and font sizes - Personalize text appearance to your preference
• 🖼️ Custom chat backgrounds - Set personalized backgrounds for conversations
• 🔤 Quick message translation - Instantly translate messages to your preferred language
• 😊 Express emotions with 80+ Emojis - Enhanced emoji reactions for messages
• 🔒 Anti-message peeking protection - Prevent others from secretly viewing your messages
• 👁️ Hide status indicators - Hide "typing", "delivered" and "read" status from others
• 📱 Native Integration - Seamlessly integrated during build process

Note: ZaDark is licensed under MPL-2.0 and is developed by Quaric. The setup process automatically prepares ZaDark, and build process integrates it seamlessly!

🚀 Quick Start

Usage

We strongly recommend using Gear Lever to integrate the AppImage perfectly into your system menu.

Note: Zalo for Linux comes with a built-in updater. Whenever a new release is available, you will be prompted within the Zalo app to download and apply the update seamlessly without leaving the application.

1. Download the latest .AppImage file from the Releases page.
2. Install Gear Lever from Flathub.
3. Open Gear Lever.
4. Click the "Open" button in the top-left corner and select the .AppImage file you downloaded.
5. The app will now appear in Gear Lever. Click the "Unlock" button, then choose "Move to the app menu" to integrate it into your system's application launcher.

Native packages

Every release also ships native packages for the standard variants — light installers (~200MB). The package manager installs the small bridge-side GStreamer stack (64-bit), Xvfb and the 32-bit libraries from the distro repos, and the install script downloads the verified wine 11.17 classic into the app — calls work immediately after install (the 32-bit GStreamer stack for the camera ships inside the app itself; distro wines are too old — e.g. wine 9.0 on Ubuntu 24.04 — or wow64-only, which breaks video calls; offline installs fall back to the app's first-run download):

• .deb for Debian/Ubuntu/Linux Mint (needs universe)
• .rpm for Fedora/openSUSE
• .pacman for Arch (install with sudo pacman -U <file>; the multilib repo must be enabled)

Both standard variants (with and without ZaDark) are published in all formats. The Full variants (call engine bundled inside, works with zero setup on any distro) remain AppImage-only.

Build from Source

Prerequisites:

• Linux x86_64
• Node.js and npm
• 7z (p7zip-full) for extracting the macOS app during setup
• C++ build tools (for native addons): build-essential, libssl-dev, liblzma-dev
• The zcall-bridge call-engine toolchain (see the apt command below)
• docker (optional — only for bundling the self-contained 64-bit GStreamer into the Full variants; without it the Full AppImage falls back to the host's GStreamer at runtime)

On Debian/Ubuntu:

sudo dpkg --add-architecture i386
sudo apt-get update && sudo apt-get install -y p7zip-full build-essential libssl-dev liblzma-dev \
  gcc-mingw-w64-i686 gcc-multilib libc6-dev-i386 libx11-dev libxcb1-dev libxext-dev \
  libx11-dev:i386 libxcb1-dev:i386 libxext-dev:i386 libpipewire-0.3-0 rpm libarchive-tools

(gcc-mingw-w64-i686 builds pipebridge.exe; the multilib/i386 X11 dev packages build the 32-bit streamproxy.so capture shim; libpipewire-0.3-0 is needed by the bundled-GStreamer self-containment checks.)

Steps:

# Clone the repository
git clone https://github.com/doandat943/zalo-for-linux.git
cd zalo-for-linux
# Then initialize or update submodules
git submodule update --init --recursive

# Run setup + build (downloads DMG, extracts, patches, packages)
npm run main

The final AppImage will be in the dist/ directory.

For a detailed walkthrough of the build pipeline, scripts, environment variables, and how to add new patches, see DEVELOPMENT.md.

⚙️ How It Works

This project is not a from-scratch rewrite of Zalo. It works by:

1. Downloading the official macOS .dmg file.
2. Using 7z to extract the app.asar archive, which contains the main application logic written in JavaScript.
3. Removing incompatible native macOS files.
4. Wrapping the extracted application in a minimal, Linux-compatible Electron shell.
5. Using electron-builder to package everything into a single, portable AppImage file.

For a deeper dive into the build pipeline and patching strategy, see ARCHITECTURE.md.

For native addons (db-cross-v4, etc.), see nativelibs/README.md.

🐛 Troubleshooting & Debugging

If you encounter issues or want to inspect the app's behavior, you can easily open Chrome Developer Tools (DevTools) using the following methods:

• Keyboard Shortcut: Press Ctrl + Shift + I while the Zalo window is focused.
• Tray Menu: Right-click the Zalo tray icon and select "Toggle DevTools".

📚 More Documentation

• ARCHITECTURE.md — How the build pipeline and patches work
• DEVELOPMENT.md — Building from source, scripts, adding patches
• nativelibs/README.md — Native addons (db-cross-v4, etc.)

📄 License

This project is licensed under the MIT License. Zalo is a trademark of VNG Corporation. This project is not affiliated with or endorsed by VNG Corporation.