# How to Build Amnezia-Client from Source: Complete CMake & Qt6 Guide

> Build Amnezia-Client from source with our complete CMake and Qt6 guide. Clone the repo, install dependencies, and compile the GUI and service effortlessly.

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

---

**To build amnezia-client from source, clone the repository with submodules, install dependencies via Conan, and execute the platform-specific build script in `deploy/` that configures CMake with Qt 6.10+ to compile both the GUI client and background service.**

Amnezia-Client is the open-source VPN client from the **amnezia-vpn/amnezia-client** repository, written in C++17 and built on Qt 6. The codebase separates the user interface from the tunneling logic, using CMake as the meta-build system and Conan for third-party dependency management. This guide provides the exact commands and configuration details needed to compile the project for Linux, Windows, macOS, and Android.

## Prerequisites

Before compiling, verify your system meets the following requirements.

- **CMake ≥ 3.25** – Required to process the top-level configuration.
- **C++17 Compiler** – `gcc`/`clang` on Linux, Xcode on macOS, or Visual Studio 2022 on Windows.
- **Qt 6.10+** – Must include **Qt Core**, **Qt 5 Compatibility**, and **Qt Remote Objects** modules.
- **Conan** – Package manager to fetch OpenSSL, libssh, wintun, and other libraries.
- **Git** – With submodule support for fetching nested dependencies.

### Optional Tools

- **Qt Installer Framework** – Required only if generating installers (`.dmg`, `.exe`).
- **WIX Toolset** – Needed for Windows MSI packaging.
- **Android SDK & NDK** – Mandatory only when targeting Android.

Ensure all tools are available in your system `PATH` or export environment variables such as `QT_INSTALL_DIR` and `ANDROID_HOME` so the build scripts can locate them.

## Repository Structure

The project is organized into two distinct components that compile together:

- **`client/`** – Contains the Qt/QML GUI application and platform-specific networking utilities (e.g., `macosUtil.mm`, [`qtunixsocket.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/qtunixsocket.cpp)).
- **`service/`** – Houses the background daemon that manages VPN tunnels (OpenVPN, WireGuard, Xray-core) via cross-platform service wrappers ([`qtservice.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/qtservice.cpp), [`qtservice_unix.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/qtservice_unix.cpp), [`qtservice_win.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/qtservice_win.cpp)).

As defined in the root [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt) at line 72, the service subdirectory is excluded from mobile builds:

```cmake
if(NOT IOS AND NOT ANDROID AND NOT MACOS_NE)
    add_subdirectory(service)
endif()

```

## Step-by-Step Build Instructions

### 1. Clone Repository and Initialize Submodules

The project vendors several external libraries via submodules.

```bash
git clone https://github.com/amnezia-vpn/amnezia-client.git
cd amnezia-client/dev
git submodule update --init --recursive

```

### 2. Install Conan Dependencies

Run Conan once to download and build missing libraries into the `build/` directory.

```bash
conan install . --output-folder=build --build=missing

```

This populates OpenSSL, libssh, and wintun headers and binaries required by the VPN service layer.

### 3. Execute the Build Script

The `deploy/` directory contains wrappers that detect Qt installations and invoke CMake with the correct toolchain.

#### Linux and macOS

```bash

# Compile client and service binaries only

./deploy/build.sh

# Compile and generate distribution installers

./deploy/build.sh --installer all

```

The script automatically searches standard Qt paths (`~/Qt`, `/opt/Qt`) or respects the `QT_INSTALL_DIR` environment variable (see logic around lines 65–82 of [`deploy/build.sh`](https://github.com/amnezia-vpn/amnezia-client/blob/main/deploy/build.sh)).

#### Windows

Open a x64 Native Tools Command Prompt for Visual Studio 2022, then run:

```cmd

# Basic build

deploy\build.bat

# Build with Qt Installer Framework installer

deploy\build.bat --installer ifw

# Build with both IFW and WIX (MSI) outputs

deploy\build.bat --installer ifw --installer wix

```

### 4. Cross-Compile for Android (Optional)

From a Linux or macOS host, target Android by specifying the `android` target and desired ABIs:

```bash
./deploy/build.sh -t android --installer all --abi all

```

The script resolves the Android toolchain file, sets `ANDROID_HOME`, and configures CMake to cross-compile the Qt application (see the Android block in [`deploy/build.sh`](https://github.com/amnezia-vpn/amnezia-client/blob/main/deploy/build.sh), lines 122–154).

### 5. Locate Build Artifacts

All output resides in `deploy/build/`:

- **Desktop platforms**: `AmneziaVPN` (or `AmneziaVPN.exe`) and the `amnezia-service` binary.
- **Installers**: CPack artifacts (`.deb`, `.dmg`, `.exe`, `.msi`) appear when `--installer` flags are used.

## CMake Configuration Details

Understanding the build system helps troubleshoot linking errors or customize compilation.

### Root Configuration

The top-level [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt) (lines 33–45) sets the C++ standard, extracts version numbers, and defines `MZ_PLATFORM_NAME` based on `CMAKE_SYSTEM_NAME`. It also forces Qt build tools to run during cross-compilation:

```cmake
set(QT_BUILD_TOOLS_WHEN_CROSS_COMPILING ON)  # Line 47

```

### Conan Integration

Line 11 of [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt) includes `conan_provider.cmake`, which automatically invokes `conan install` before configuring the project. This ensures that `find_package(OpenSSL)` and similar calls resolve to Conan-managed libraries rather than system versions.

### Qt Kit Selection

The build scripts populate `CMAKE_PREFIX_PATH` with the detected Qt installation. For Android builds, they additionally pass `-DCMAKE_TOOLCHAIN_FILE` pointing to the Android NDK's CMake toolchain, enabling proper compilation of Qt's networking components for ARM architectures.

## Summary

- **Amnezia-Client** splits into a `client/` GUI and a `service/` daemon, both built via CMake.
- **Conan** handles third-party dependencies; run `conan install . --output-folder=build --build=missing` before compiling.
- **Helper scripts** in [`deploy/build.sh`](https://github.com/amnezia-vpn/amnezia-client/blob/main/deploy/build.sh) (Unix) and `deploy/build.bat` (Windows) automate Qt detection and CPack packaging.
- **Android cross-compilation** is supported from Linux/macOS hosts using the `-t android` flag.
- **Binaries** output to `deploy/build/`, with installers generated when `--installer` options are specified.

## Frequently Asked Questions

### What is the difference between the client and service components?

The **client** component provides the graphical interface and user interaction logic, while the **service** component runs as a background daemon with elevated privileges to manage VPN tunnels. The service is omitted when building for iOS or Android, where tunneling is handled by platform-specific VPN extensions rather than a standalone daemon.

### Can I build amnezia-client without Conan?

Technically possible but discouraged. The official build system relies on the `conan_provider.cmake` module (referenced at line 11 of [`CMakeLists.txt`](https://github.com/amnezia-vpn/amnezia-client/blob/main/CMakeLists.txt)) to locate **OpenSSL**, **libssh**, and platform-specific libraries like **wintun**. Manual builds would require installing these dependencies system-wide and modifying `CMAKE_PREFIX_PATH` manually, which is not tested by the upstream maintainers.

### How do I build for Android from Linux or macOS?

Use the cross-compilation mode in the build script: `./deploy/build.sh -t android --installer all --abi all`. Ensure `ANDROID_HOME` is exported and contains the Android SDK and NDK. The script automatically configures the toolchain file and builds APKs for multiple architectures.

### Where are the compiled binaries located after building?

Final executables are placed in `deploy/build/`. On desktop platforms, you will find the main `AmneziaVPN` executable alongside the `amnezia-service` binary. If you passed `--installer` flags to the build script, distribution packages (`.deb`, `.dmg`, `.exe`, or `.msi`) are generated in the same directory via CPack.