Installing

Download pre-built binaries for a release

There are pre-built binaries of the last released version of Mozilla VPN for Windows, Mac, Linux, Android iOS and Wasm.

Table Of Contents

• Linux
  • Flatpak
  • Debian & Ubuntu (.deb)
  • Fedora (.rpm)
  • From Source
• Android
  • Google Play
  • Non Google Play devices
  • From Source
• Windows
  • Windows 10&11 x64
  • Windows 11 aarch64
  • From Source
• macOS
  • From Source
• iOS
  • From Source
• WASM
  • From Taskcluster artifacts
  • From Source

Linux

Flatpak

The Mozilla VPN client supports building and distribution via flatpak, and is available on Flathub at org.mozilla.vpn.

Building the Flatpak

The flatpak manifests for the latest stable release can be found at flathub/org.mozilla.vpn, and this project also contains a manifest for local development in the linux/flatpak directory.

To build the flatpak package, start by installing the org.flatpak.Builder app:

flatpak install -y flathub org.flatpak.Builder

Add the Flathub repo user-wide:

flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo

Then build the project manifest and install it:

flatpak run org.flatpak.Builder --force-clean --sandbox --user --install --install-deps-from=flathub --ccache build-flatpak linux/flatpak/org.mozilla.vpn.yml

Once installed, the Mozilla VPN client can be run using the org.mozilla.vpn app identifier:

   flatpak run org.mozilla.vpn

Debian & Ubuntu (.deb)

Mozilla APT repository (recommended)

Supported on Ubuntu 22.04+, Linux Mint 20+, and Debian 11+.

sudo install -d -m 0755 /etc/apt/keyrings
wget -q https://packages.mozilla.org/apt/repo-signing-key.gpg -O- | sudo tee /etc/apt/keyrings/packages.mozilla.org.asc > /dev/null

Verify the key fingerprint matches 35BAA0B33E9EB396F59CA838C0BA5CE6DC6315A3:

gpg -n -q --import --import-options import-show /etc/apt/keyrings/packages.mozilla.org.asc | awk '/pub/{getline; gsub(/^ +| +$/,""); if(\$0 == "35BAA0B33E9EB396F59CA838C0BA5CE6DC6315A3") print "\nThe key fingerprint matches ("\$0").\n"; else print "\nVerification failed: the fingerprint ("\$0") does not match the expected one.\n"}'

Add the repository and install:

echo "deb [signed-by=/etc/apt/keyrings/packages.mozilla.org.asc] https://packages.mozilla.org/apt mozilla main" | sudo tee -a /etc/apt/sources.list.d/mozilla.list > /dev/null
sudo apt-get update && sudo apt-get install mozillavpn

Manual .deb download

Past releases are available at archive.mozilla.org. Download the .deb for your release and install with:

sudo dpkg -i mozillavpn-<version>.deb

Fedora (.rpm)

RPM packages are available at archive.mozilla.org. Download the .rpm for your release and install with:

sudo dnf install ./mozillavpn-<version>.rpm

From Source

Clone the repository and install build dependencies.

# For Debian-ish
sudo apt-get install devscripts equivs
mk-build-deps --install --remove linux/debian/control
# For Fedora-ish
sudo dnf builddep --define "_version 0" linux/mozillavpn.spec

Then install the Python build dependencies:

pip install -r requirements.txt

Then configure and build:

cmake -S . -B build -GNinja -DCMAKE_INSTALL_PREFIX="/"
cmake --build build
sudo cmake --install build

The built binary is at build/src/mozillavpn. Note that wireguard-tools is also required at runtime. You can run the app with mozillavpn Alternatively, you can use two terminals to run the daemon manually sudo mozillavpn linuxdaemon and separately mozillavpn

Android

Google Play

We are in the Google Play Store older versions can be fetched from archive.mozilla.org.

Non Google Play devices

Using APK file

For devices that do not support Google-Play Services, a non-GPS build can be downloaded from archive.mozilla.org or GitHub releases. Look for the android directory (if you are using archive.mozilla.org) and select the mozillavpn-foss-* APK file that matches your device's architecture.

Verify certificate hash before installing (optional)

This is the SHA-256 fingerprint of the certificate used to sign the Apk's 33:5D:AB:EB:46:9D:40:D7:77:90:31:D9:AE:E3:B8:56:8E:01:DB:52:BF:C3:C1:AF:60:40:B5:39:9A:51:7A:3C

You can use the following command to retrieve the signing certificate fingerprint of the file: apksigner verify -v --print-certs ./path/to/mozillavpn-foss.apk

To verify the authenticity of the downloaded APK, ensure that the field Signer #1 certificate SHA-256 digest matches the certificate hash above.

Using Obtainium

Obtainium is an handy tool for installing and updating Android apps directly from their release channels (GitHub releases, websites, etc.). You can download Obtainium from the official website or from F-Droid.

Install procedure:

• Install and open Obtainium
• Tap "Add app"
• Search for "mozilla vpn"
• Select GitHub source and tap "Search"
• Select "mozilla-mobile/mozilla-vpn-client" and tap "Pick"
• Tap "Add"
• Select the "mozillavpn-foss-*" build and tap "Continue" (Obtainium will automatically choose the correct packages for your device architecture)
• Wait for the download to complete, then tap "Install" and select the mozilla-vpn-foss* file again
• Mozilla VPN is now installed

From Source

Please install miniconda.

$ conda env create -f env-android.yml
$ conda activate vpn-android
# Optional: If another aarch then arm64-v8a is needed do:
$ conda env config vars set ANDROID_ARCH=x86
# Valid architecture values: `x86`, `x86_64`, `armeabi-v7a` `arm64-v8a`.
# Optional: If another QT Version is needed do: 
$ conda env config vars set QT_VERSION=1.2.3
# Re-Activate the ENV to apply changes. 
$ conda deactivate
$ conda activate vpn-android

# Setup the Android SDK and NDK for the current Conda env.
$ ./scripts/android/conda_setup_sdk.sh
# Setup the Conda env to fetch and use QT
$ ./scripts/android/conda_setup_qt.sh
$ conda deactivate
$ conda activate vpn-android

Trigger a build with:

$ ./scripts/android/cmake.sh -d 

Windows

Windows 10&11 x64

Get the installer of the latest release here, you can find past versions on archive.mozilla.org.

Windows 11 aarch64

[!INFO] We don't consider those builds rock-stable

We don't have any stable arm64 builds yet, you can however help us test by grabbing the latest release from archive.mozilla.org. Look for windows MozillaVPN-aarch64.msi

From Source

Have miniconda installed.

[!INFO] You may need to enable powershell scripts. You can call Set-ExecutionPolicy -ExecutionPolicy Unrestricted

$ cd mozilla-vpn-client
$ conda env create -f env-windows.yml
$ conda activate vpn
# Download the Windows SDK using Xwin
$ ./scripts/windows/conda-setup-xwin-sdk.ps1
# Setup the conda env to use a prebuild Qt from Moz-CI
$ ./scripts/windows/conda_setup_win_qt.ps1
# Reactivate the env to apply the changes:
$ conda deactivate
$ conda activate vpn

# Configure
$ cmake -S . -B build -GNinja

# Compile
$ cmake --build build

macOS

Get the installer of the latest release here, you can find past versions on archive.mozilla.org.

From Source

Install Xcode - https://developer.apple.com/xcode/

Before you start this process, open Xcode, go to settings, accounts, and sign in with your Apple ID. If you are a Mozilla developer, this is an Apple ID associated with your LDAP account.

$ cd mozilla-vpn-client
$ conda env create -f env-apple.yml
$ conda activate vpn
$ ./scripts/macos/conda_setup_qt.sh
# Reactivate the env to apply the changes:
$ conda deactivate
$ conda activate vpn

# Configure
$ cmake -S . -B build -GNinja -DCODE_SIGN_IDENTITY=<signing identity>

# Compile
$ cmake --build build
# Run 
$ open ./build/src/Mozilla\ VPN.app

Many features of the Mozilla VPN project depend on having a valid code signature. To determine the codesigning identities available to you, you can use the security tool on the command line as follows:

user@example ~ % security find-identity -v -p codesigning                
  1) AAAABBBBCCCCDDDDEEEEFFFFAAAABBBBCCCCDDDD "Apple Development: Jane Doe (XXXXXXXXXX)"
     1 valid identities found

Thus, to configure the project to use the above codesigning identity, we can provide the argument -DCODE_SIGN_IDENTITY=AAAABBBBCCCCDDDDEEEEFFFFAAAABBBBCCCCDDDD

To distribute a signed application for installation on other machines, an embedded provisioning profile is also required. The path to the provisioning profile can be specified with the argument -DCODE_SIGN_PROFILE=<path/to/embedded.provisionprofile>. When this argument is unset, an attempt will be made to automatically lookup the provisioning profile from the ~/Library/Developer/Xcode/UserData/Provisioning\ Profiles directory.

Building the installer

Use the --target macpkg to build the MacOS installer.

This will produce an macOS installer package at build-macos/macos/pkg/MozillaVPN.pkg

Building with Xcode

Use the same configure command above and use -GXcode as the CMake generator:

cmake -S . -B build-macos -DCMAKE_PREFIX_PATH=<Qt unzipped path>/macos/lib/cmake/ -GXcode

This will generate an Xcode project file at build-macos/Mozilla VPN.xcodeproj which can be opened by Xcode:

open build-macos/Mozilla\ VPN.xcodeproj

Once Xcode has opened the project, select the mozillavpn target and start the build.

iOS

Get the latest release in the Apple App Store.

From Source

Install Xcode - https://developer.apple.com/xcode/

Before you start this process, open Xcode, go to settings, accounts, and sign in with your Apple ID. If you are a Mozilla developer, this is an Apple ID associated with your LDAP account.

[!CAUTION] _Xcode 26 has changed where iOS SDKs are stored. Symbolic links must be created so qt-cmake can find the SDK. (If a future version of qt-cmake changes how it looks for iOS SDKs, this section can be removed.)

$ cd /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/
$ ln -s iPhoneOS.sdk iPhoneOS26.0.sdk # (for iOS 26.0 - change the version number for other SDK versions)

Important: The specific iOS SDK versions must also be downloaded via Xcode. Creating a symbolic link will not download the SDK automatically.

If the macOS conda environment has not already been installed, install it:

$ conda env create -f env-apple.yml -n vpn
$ conda activate vpn
# Setup QT
$ ./scripts/macos/conda_setup_qt.sh
# Check for correctness:
$ which qt-cmake # should be ~/miniconda3/envs/vpn/bin/qt-cmake

qt-cmake -S . -B build-ios \
    -GXcode -DQT_HOST_PATH_CMAKE_DIR=~/Qt/6.10.1/macos/lib/cmake \
    -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS26.0.sdk

(Older qt-cmake versions used the -DQT_HOST_PATH=~/Qt/6.6.3/macos flag rather than QT_HOST_PATH_CMAKE_DIR shown here. If having issues, try the older format.)

If you get the error No CMAKE_Swift_COMPILER could be found., include the flag with the direct path the Swift compiler:

qt-cmake -S . -B build-ios -GXcode -DQT_HOST_PATH_CMAKE_DIR=~/Qt/6.10.1/macos/lib/cmake -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS26.0.sdk -DCMAKE_Swift_COMPILER=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/swiftc

This will generate an Xcode project file at build-ios/Mozilla VPN.xcodeproj which can be opened by Xcode:

open build-ios/Mozilla\ VPN.xcodeproj

Once Xcode has opened the project, select the mozillavpn target and start the build.

Tips:

• If you can't see a simulator target in the Xcode interface, look at Product -> Destination -> Destination Architectures -> Show Both
• Due to lack of low level networking support, it is not possible to turn on the VPN from the iOS simulator in Xcode.

WASM

WASM builds allow running the VPN client UI in a browser, primarily for development and testing purposes. Try it in the browser

From Source

Install miniconda, then create and activate the WASM conda environment:

conda env create -f env-wasm.yml
conda activate vpn

Install EMSDK and Qt for WASM:

./scripts/wasm/conda_setup_emsdk.sh
./scripts/wasm/conda_setup_qt.sh
# Re-activate to apply changes
conda deactivate && conda activate vpn

Configure and build:

qt-cmake -S . -B build-wasm -GNinja \
    -DCMAKE_BUILD_TYPE=MinSizeRel \
    -DBUILD_TESTS=OFF
cmake --build build-wasm

You will find the index.html in ./build-wasm/wasm-build/index.html

Troubleshooting

git clean if you're having build troubles

It's easy for your local build to get messed up. When in doubt do a git clean to blow away all generated files. Running git clean -xfdi . from the root of the folder provides you an interactive space where you can review everything that's going to be deleted. You may want to exclude .vscode or .env that you've set-up just the way you like.

did you activate your conda environment?

You'll need to run conda activate vpn (or vpn-android for Android) every time you open a new terminal. If you forget and then run cmake the build can get confused / stuck. git clean, make sure conda environment is activated, try again.

ask for help

We are on a mission to make building easy. If you've tried the above two steps, don't get stuck ask for help.