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

• Can't make or receive calls: The call module (zcall) only ships as a macOS native binary.
• 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.

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

On Debian/Ubuntu:

sudo apt-get update && sudo apt-get install -y p7zip-full build-essential libssl-dev liblzma-dev

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.