How to Build the Amnezia VPN Client from Source on Linux, Windows, and Android

You can build the Amnezia VPN client from source by cloning the dev branch of the amnezia-vpn/amnezia-client repository, installing CMake, Qt 6.10+, and Conan, then executing the platform-specific helper scripts in deploy/build.sh or deploy/build.bat to configure, compile, and optionally package the binaries.

The Amnezia VPN client is a cross-platform desktop and mobile application written in C++/Qt that targets Linux, macOS, Windows, and Android. According to the amnezia-vpn/amnezia-client source code, the build system is driven by CMake with dependency management handled by Conan, while orchestration scripts in the deploy directory automate tool-chain discovery and installer generation.

Prerequisites and Required Toolchain

Before you compile the Amnezia VPN client from source, install the following components:

• CMake – A recent version for project generation.
• C/C++ compiler – GCC or Clang on Linux, Xcode on macOS, or MSVC on Windows.
• Qt 6.10 or later – Including the Core, Qt 5 Compatibility, and Remote Objects modules.
• Conan – For pulling third-party dependencies such as OpenSSL and XRay-core.
• Ninja – Required when targeting Android.

Optional packaging tools include the Qt Installer Framework (IFW) for .run, .dmg, and .exe installers, and WiX for creating MSI packages on Windows. Detailed prerequisite coverage is located in the repository’s [README.md](https://github.com/amnezia-vpn/amnezia-client/blob/dev/README.md#L88-L103) on the dev branch.

High-Level Build Workflow

The build process implemented in the Amnezia VPN source code follows three distinct phases:

1. Dependency resolution – Conan installs required libraries via conanfile.py.
2. CMake configuration – The top-level CMakeLists.txt defines the project structure, embeds Qt integration, and adds the client and service subdirectories.
3. Compilation and packaging – The deploy/build.sh or deploy/build.bat script detects the host OS, resolves Qt paths, invokes the correct CMake generator, runs the build, and calls CPack to produce installers when requested.

Platform-Specific Build Instructions

Linux and macOS

On Unix-like hosts, the deploy/build.sh script handles Qt discovery under ~/Qt or /opt/Qt (or a custom path defined by QT_INSTALL_DIR), selects the Unix Makefiles generator, and sets CMAKE_PREFIX_PATH to the appropriate Qt directory (for example, gcc_64 on Linux or macos on macOS).

# Clone the repository including submodules

git clone --recursive https://github.com/amnezia-vpn/amnezia-client.git
cd amnezia-client
git checkout dev

# Install Conan dependencies

conan install . --build=missing

# Build the client executable

./deploy/build.sh

# Build the client and create an installer with Qt IFW

./deploy/build.sh --installer all

When --installer all is supplied, CPack invokes the IFW generator to produce a .run installer on Linux or a .dmg on macOS.

Windows

On Windows, open a Developer Command Prompt (for example, VS 2022 x64 Native Tools) so that the MSVC tool-chain is available. The deploy/build.bat script searches for Qt under C:\Qt or %QT_INSTALL_DIR%, selects the Visual Studio 17 2022 generator, and builds the client.

:: Clone the repository
git clone --recursive https://github.com/amnezia-vpn/amnezia-client.git
cd amnezia-client
git checkout dev

:: Build the executable only
deploy\build.bat

:: Build and package with Qt IFW and WiX
deploy\build.bat --installer all

After compilation, CPack generates a .exe installer via IFW. Supplying --installer wix instead produces an MSI package.

Android

Android builds require the Android SDK, NDK, Ninja, and a Qt for Android installation. The deploy/build.sh script detects the SDK via ANDROID_HOME or ANDROID_SDK_ROOT, selects the NDK version matching ANDROID_NDK_VERSION, and targets the Qt Android ABI folder (for example, android_arm64_v8a).

# Clone and prepare the source

git clone --recursive https://github.com/amnezia-vpn/amnezia-client.git
cd amnezia-client
git checkout dev

# Build APKs for the default ABIs and produce an AAB (Android App Bundle)

./deploy/build.sh -t android --aab

The script compiles the default ABI set (arm64-v8a, armeabi-v7a, x86, x86_64). Passing --aab adds a secondary target that outputs an AAB file. If --sign is provided and a signing key is configured, the artifacts are signed automatically.

Key Build Files and Source Components

Top-Level CMake Configuration

The root [CMakeLists.txt](https://github.com/amnezia-vpn/amnezia-client/blob/dev/CMakeLists.txt#L1-L79) on the dev branch defines the project name and version, integrates Qt via find_package, pulls in Conan packages, and adds the client and service subdirectories. Lines 1–79 contain the full top-level configuration.

Build Orchestration Scripts

[deploy/build.sh](https://github.com/amnezia-vpn/amnezia-client/blob/dev/deploy/build.sh#L1-L222) serves as the cross-platform build driver for Linux, macOS, and Android. It assembles the CMake command line, selects the correct generator and tool-chain, runs cmake --build, and invokes CPack. The Windows equivalent, deploy/build.bat, performs the same role for MSVC-based builds.

Core Application Sources

• client/vpnConnection.cpp and client/vpnConnection.h – Implement the high-level VPN connection logic consumed by the UI. The full sources are available at [client/vpnConnection.cpp](https://github.com/amnezia-vpn/amnezia-client/blob/dev/client/vpnConnection.cpp) and [client/vpnConnection.h](https://github.com/amnezia-vpn/amnezia-client/blob/dev/client/vpnConnection.h).
• service/server/main.cpp – Provides the entry point for the background VPN service on Linux and macOS.
• conanfile.py – The Conan recipe that declares third-party dependencies, including OpenSSL, Qt components, and XRay-core.

End-to-End Build Example

The following command sequence demonstrates a complete build on Linux, producing both executables and an installer:

# 1. Clone the dev branch with all submodules

git clone --recursive https://github.com/amnezia-vpn/amnezia-client.git
cd amnezia-client
git checkout dev

# 2. Resolve Conan dependencies

conan install . --build=missing

# 3. Compile and package

./deploy/build.sh --installer all

# 4. Locate the outputs

ls build/bin          # client and service binaries

ls build/packages     # IFW installer package

Running the equivalent script on macOS or Windows follows the identical logical flow, with deploy/build.sh or deploy/build.bat automatically adapting the generator, tool-chain, and CPack format to the host platform.

Summary

• The Amnezia VPN client source is built from the dev branch using CMake, Conan, and Qt 6.10+.
• The top-level CMakeLists.txt configures the project, while deploy/build.sh and deploy/build.bat automate platform-specific discovery and compilation.
• On Linux and macOS, the script produces executables and optionally .run or .dmg installers via CPack and Qt IFW.
• On Windows, MSVC builds yield .exe installers through IFW, with optional MSI generation via WiX.
• On Android, the same script cross-compiles for multiple ABIs and can output signed APKs or AAB bundles.

Frequently Asked Questions

What dependencies are required to build Amnezia VPN from source?

You need a recent CMake, a C/C++ compiler, Qt 6.10 or later with Core, Qt 5 Compatibility, and Remote Objects modules, plus Conan for dependency management. Optional tools such as the Qt Installer Framework and WiX are only needed if you intend to generate installer packages.

How do I generate an installer instead of only the compiled binary?

Pass --installer all to deploy/build.sh on Linux or macOS, or to deploy/build.bat on Windows. This triggers CPack with the Qt IFW generator after compilation. On Windows, you can additionally pass --installer wix to produce an MSI package.

Which repository branch should I use to compile the latest client?

Use the dev branch of the amnezia-vpn/amnezia-client repository, where the build scripts, top-level CMakeLists.txt, and Conan recipes are actively maintained. This branch contains the latest client source code and is the recommended target for compilation.

Can I build the Android client from the same source tree?

Yes. The same repository and deploy/build.sh script support Android when you provide the Android SDK, NDK, Ninja, and Qt for Android. Invoke the script with -t android --aab to build APKs for the default ABIs and produce an Android App Bundle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}