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

> Build the Amnezia VPN client from source easily on Linux Windows and Android. Follow our guide to compile the latest version using CMake Qt and Conan.

- Repository: [Amnezia VPN/amnezia-client](https://github.com/amnezia-vpn/amnezia-client)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/conanfile.py).
2. **CMake configuration** – The top-level [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt) defines the project structure, embeds Qt integration, and adds the `client` and `service` subdirectories.
3. **Compilation and packaging** – The [`deploy/build.sh`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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).

```bash

# 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.

```batch
:: 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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`).

```bash

# 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/main/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/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/vpnConnection.cpp)** and **[`client/vpnConnection.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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/main/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/main/client/vpnConnection.h)](https://github.com/amnezia-vpn/amnezia-client/blob/dev/client/vpnConnection.h).
- **[`service/server/main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/service/server/main.cpp)** – Provides the entry point for the background VPN service on Linux and macOS.
- **[`conanfile.py`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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:

```bash

# 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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt)** configures the project, while **[`deploy/build.sh`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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.