Building the App

Build Mullvad VPN from source for all supported platforms

Overview

This guide covers building the Mullvad VPN app from source for desktop (Windows, macOS, Linux), Android, and iOS platforms.

Prerequisites

All Platforms

Rust Toolchain

Get the latest stable Rust toolchain via rustup.rs.

Install default targets and components for your platform:

./scripts/setup-rust android|ios|windows|linux|macos

Optionally, install a git post-checkout hook that automatically runs setup-rust when the Rust version changes:

./scripts/setup-rust install-hook

Node.js and npm

You need Node.js 22.21.1 and npm 11.7.0 (specified in the volta section of desktop/package.json).

Linux:

# Follow instructions on volta.sh
curl https://get.volta.sh | bash

macOS:

brew install volta && volta setup

Windows: Install the msi from volta-cli/volta

Go

Install Go 1.21 or newer from golang.org.

Protobuf Compiler

Install protobuf compiler version 3.15 or later:

• Linux: protobuf-compiler package, plus:
  • Fedora: protobuf-devel
  • Debian/Ubuntu: libprotobuf-dev
• macOS: brew install protobuf
• Windows: Download binaries from GitHub and add to PATH

Bash

Bash 4.0 or later must be installed and available in PATH on all platforms.

• Linux: Usually installed by default
• macOS: Install via Homebrew: brew install bash (default 3.2.5 is not supported)
• Windows: Install Git for Windows which includes Git Bash

Linux

Debian/Ubuntu

# For building the daemon
sudo apt install gcc libdbus-1-dev
# For building the installer
sudo apt install rpm

Fedora/RHEL

# For building the daemon
sudo dnf install dbus-devel
# For building the installer
sudo dnf install rpm-build

Cross-compiling for ARM64

# Debian
sudo dpkg --add-architecture arm64
sudo apt update
sudo apt install libdbus-1-dev:arm64 gcc-aarch64-linux-gnu

rustup target add aarch64-unknown-linux-gnu

Add to ~/.cargo/config.toml:

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

[target.aarch64-unknown-linux-gnu.dbus]
rustc-link-search = ["/usr/aarch64-linux-gnu/lib"]
rustc-link-lib = ["dbus-1"]

Nix Devshell

Supported on Linux (x86_64) and macOS (x86_64 and aarch64):

nix develop

Optionally use direnv for automatic sourcing:

direnv allow .

Windows

Required components:

• Build Tools for Visual Studio 2022 (or Visual Studio 2022 Community/Pro)

• Windows 10/11 SDK

• Bash and Unix utilities (see All Platforms section)

• zig 0.14 or later, available in PATH: ziglang.org/download

• msbuild.exe available in PATH:

  C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\<arch>
  

  Or source vcvars.sh: . ./scripts/vcvars.sh

• x86 target for NSIS plugins:

  rustup target add i686-pc-windows-msvc
  

Cross-compiling for ARM64

Requirements:

• ARM64 MSVC tools in Visual Studio
• clang on PATH
• ARM64 Rust target:
  rustup target add aarch64-pc-windows-msvc
  

Compiling on Windows ARM

Additional requirements:

• clang from Visual Studio in PATH
• Correct INCLUDE environment variable (run vcvarsall.bat arm64 or source vcvars.sh)
• x64 grpc-tools binaries:
  pushd desktop/packages/mullvad-vpn
  npm install --target_arch=x64 grpc-tools
  popd
  

macOS

Required:

• Recent version of bash (not the default 3.2.57)
• clang for CGo

Android

See the Android Build Instructions for detailed setup including:

• JDK 17
• Android SDK and NDK
• Android-specific Rust targets

iOS

Required dependencies:

• Go 1.21: brew install go@1.21
• Rust with iOS targets: ./scripts/setup-rust ios
• Protobuf compiler: brew install protobuf
• Xcode configuration with team ID and provisioning profiles

Building the Complete App

Desktop Platforms

The simplest way to build the entire app and generate an installer:

./build.sh [--optimize]

Add --optimize to enable compiler optimizations (longer build, smaller binaries).

This produces an installer (exe, pkg, rpm, or deb) in the dist/ directory.

Minimum memory requirement: 1GB

Target-Specific Builds

macOS Universal Binary:

./build.sh --universal

Linux ARM64:

TARGETS="aarch64-unknown-linux-gnu" ./build.sh

Windows ARM64:

TARGETS="aarch64-pc-windows-msvc" ./build.sh

Android

Containerized build (recommended):

# Debug build
../building/containerized-build.sh android --dev-build

# Release build
ANDROID_CREDENTIALS_DIR=/path/to/credentials ../building/containerized-build.sh android --app-bundle

Manual build:

# Debug build
../android/build.sh --dev-build

# Release build
../android/build.sh --app-bundle

iOS

Configure Xcode project:

for file in ./ios/Configurations/*.template ; do cp $file ${file//.template/} ; done

Edit the generated .xcconfig files with your team ID and provisioning profiles.

Then build through Xcode or command line tools.

Building Individual Components

Mullvad Daemon

1. macOS only: Source environment variables:

   source env.sh
   

2. Windows only: Build C++ libraries:

   ./build-windows-modules.sh
   cp dist-assets/binaries/x86_64-pc-windows-msvc/wintun.dll target/debug/
   

3. Build the daemon:

   cargo build
   

4. Windows only: Run as SYSTEM user using PsExec:

   psexec64 -i -s bash.exe
   

5. Run the daemon:

   # Linux/macOS
   sudo MULLVAD_RESOURCE_DIR="./dist-assets" ./target/debug/mullvad-daemon -vv
   
   # Windows (already in SYSTEM shell)
   MULLVAD_RESOURCE_DIR="./dist-assets" ./target/debug/mullvad-daemon -vv
   

Desktop Electron App

1. Navigate to desktop directory:

   cd desktop
   

2. Install dependencies:

   npm install -w mullvad-vpn
   

3. Start in development mode:

   npm run -w mullvad-vpn develop
   

Changes to JavaScript files will automatically reload.

Note: The Electron app requires a running daemon to connect to.

Development Commands

Desktop/Electron

npm run develop          # Develop with live-reload
npm run lint            # Lint code
npm run pack:<OS>       # Package for distribution (linux/mac/win)
npm test                # Run tests

Rust/Cargo

cargo build             # Build daemon and tools
cargo test              # Run tests
cargo build --release   # Optimized release build
cargo build --workspace # Build all workspace crates

Special Build Cases

ARM64 Linux Hosts

Due to protobuf limitations, building on ARM64 Linux requires a 2-stage process:

1. Build proto files on non-ARM64 platform:

   cd desktop
   npm ci -w mullvad-vpn
   npm run -w mullvad-vpn build-proto
   

2. Copy proto files from:

   • desktop/packages/mullvad-vpn/src/main/management_interface/
   • desktop/packages/mullvad-vpn/build/src/main/management_interface/

3. Build on ARM64 with proto files:

   MANAGEMENT_INTERFACE_PROTO_BUILD_DIR=/path/to/proto ./build.sh --dev-build
   

   May also need: USE_SYSTEM_FPM=true

Troubleshooting

Build requires at least 1GB memory

If builds fail with memory errors, ensure your system has adequate RAM or increase swap space.

Protobuf compiler not found

Ensure protoc is in your PATH and version 3.15+:

protoc --version

Node/npm version mismatch

Use Volta to automatically manage Node.js versions:

volta install node@22.21.1

Bash version too old (macOS)

The default macOS bash (3.2.5) is too old. Install bash 4.0+:

brew install bash