90
Building KeePassXC
Janek Bevendorff edited this page 2026-11-11 23:27:36 +01:00

Required Dependencies

KeePassXC supports the following Operating Systems:

  • Windows 10 and 11
  • MacOS 12.0+
  • Ubuntu Linux 22.04+

The following build tools must exist in your PATH:

  • cmake (>= 3.22.1)
  • make (>= 4.3) or ninja (>= 1.10.1)
  • g++ (>= 11.2) or clang++ (>= 14.0)
  • asciidoctor (>= 2.0.16)

Besides a working C++ toolchain, KeePassXC also has a number of direct build and runtime dependencies. For detailed information about how to install them, please see Set up Your Build Environment below.

Build Options

KeePassXC comes with a variety of build options that can turn on/off features. Most notably, we allow you to build the application with all TCP/IP networking code disabled. Please note that we still require and link against Qt5's network library in order to use local named pipes on all operating systems. Each of these build options are supplied at the time of calling cmake.

-DKPXC_MINIMAL=[ON|OFF] Build KeePassXC with the minimal feature set required for basic usage (default: OFF)
-DKPXC_FEATURE_BROWSER=[ON|OFF] Browser integration and passkeys support (default: ON)
-DKPXC_FEATURE_SSHAGENT=[ON|OFF] SSH Agent integration (default: ON)
-DKPXC_FEATURE_FDOSECRETS=[ON|OFF] freedesktop.org Secret Service integration; replace system keyring (default: ON)
-DKPXC_FEATURE_NETWORK=[ON|OFF] Include code that reaches out to external networks (e.g. downloading icons) (default: ON)
-DKPXC_FEATURE_UPDATES=[ON|OFF] Include automatic update checks; disable for managed distributions (default: ON)
-DKPXC_FEATURE_DOCS=[ON|OFF] Build offline documentation; requires asciidoctor tool (default: ON)

-DWITH_TESTS=[ON|OFF] Enable building of unit tests (default: ON)
-DWITH_GUI_TESTS=[ON|OFF] Enable building of GUI tests (default: OFF)
-DWITH_WARN_DEPRECATED=[ON|OFF] Development only: warn about deprecated methods, including Qt. (default: OFF)
-DWITH_ASAN=[ON|OFF] Enable address sanitizer checks (Linux / macOS only) (default: OFF)
-DWITH_COVERAGE=[ON|OFF] Use to build with coverage tests (GCC only). (default: OFF)
-DWITH_APP_BUNDLE=[ON|OFF] Enable Application Bundle for macOS (default: ON)
-DWITH_CCACHE=[ON|OFF] Use ccache for build (default: OFF)
-DWITH_X11=[ON|OFF] Enable building with X11 dependencies (default: ON)
-DWITH_BUILD_QT=[ON|OFF] Build Qt6 as a dependency (default: OFF)

-DKEEPASSXC_BUILD_TYPE=[Snapshot|Release] Set the build type to show/hide stability warnings (default: "Snapshot")
-DOVERRIDE_VERSION=[X.X.X] Specify a version number when building. Used with snapshot builds (default: "")
-DKEEPASSXC_DIST_TYPE=[Native|Snap|AppImage|Flatpak] Specify the distribution method (default: "Native")
-DGIT_HEAD_OVERRIDE=[XXXXXXX] Specify the 7 digit git commit ref for this build. Used with distribution builds (default: "")
-DWITH_SBOM=[ON|OFF] Generate an SPDX SBOM of the deployment (requires Syft and Python spdx-tools) (default: OFF)

Building Manually

1. Set up your build environment

Use the following guides to setup your build environment:

2. Building

The following steps assume you have installed Qt with a package manager in a standard location where CMake can find it.

If Qt is not located in a default location (e.g., when installed manually from qt.io), you have to add -DCMAKE_PREFIX_PATH=<PATH TO QT> to your cmake command (e.g., -DCMAKE_PREFIX_PATH="$HOME/Qt/6.12.0/macos). Alternatively, you can set the Qt6_DIR environment variable to the Qt install location.

If, instead, you prefer to build Qt via vcpkg, you can simply add -DWITH_BUILD_QT=ON to the cmake command. However, be aware that building Qt may take a very long time.

Download Sources

Download the sources from keepassxc.org and unpack them:

tar xf keepassxc-*-src.tar.xz

or pull them directly from Git (note: default branch is develop):

git clone https://github.com/keepassxreboot/keepassxc.git

Now change into the source directory and run the following commands, depending on your platform.

Linux

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j8
sudo make install

If you don't want to install KeePassXC at all, you can also run it directly from the build directory:

./src/keepassxc

macOS

Download and unpack the source code as described in the Linux section, change into the source code directory and run:

mkdir build
cd build
cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$HOME/Qt/6.12.0/macos" \
  -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"  ..
make -j8 package

Replace $HOME/Qt/6.12.0/macos with the path to your Qt installation and make sure that $VCPKG_ROOT points to your vcpkg installation. Omit -DCMAKE_TOOLCHAIN_FILE and -DCMAKE_PREFIX_PATH` if you installed dependencies via Homebrew.

If you build Qt via vcpkg (with -DWITH_BUILD_QT=ON), also add -DVCPKG_TARGET_TRIPLET=arm64-osx-dynamic-release or x64-osx-dynamic-release if you compile for Intel Macs. Setting the correct triplet is important! The default arm64-osx or x64-osx triplets will compile Qt as a static library, which will result in lots of linker errors that will give you lots of headaches.

When building with ASAN support on macOS, you need to use export ASAN_OPTIONS=detect_leaks=0 before running the tests (LSAN is no supported on macOS).

Windows

The preferred way to build on Windows is using MSVC, for which you have to open an MSVC Tools Command Prompt.

Download and unpack the source code as described in the Linux section. To build KeePassXC with MSVC, open a (Visual Studio Developer) PowerShell, change into the source code directory, and run:

mkdir build
cd build
cmake -G Ninja `
  -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_PREFIX_PATH="C:\Qt\6.12.0\msvc2022_64" `
  -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake" ..
ninja -j8

Replace C:\Qt\6.12.0\msvc2022_64 with the path to your Qt installation.

Make sure that -DCMAKE_TOOLCHAIN_FILE points to the correct path of your vcpkg installation. If vcpkg is installed as part of Visual Studio and you opened a Developer PowerShell, $env:VCPKG_ROOT should already be defined. In case it's undefined, replace it with the prefix of your vcpkg installation. The vcpkg installed with Visual Studio is usually located at C:\Program Files\Microsoft Visual Studio\18\Community\VC\vcpkg (replace 18 with your version number).

To package the build into a ZIP and MSI distributable use:

cpack -G ZIP;MSI

If you build with Msys2, omit -DCMAKE_TOOLCHAIN_FILE and -DVCPKG_TARGET_TRIPLET altogether and add -G "MSYS Makefiles" instead.

3. Running tests

If you compiled KeePassXC with the CMake flags -DWITH_TESTS=ON and -DWITH_GUI_TESTS=ON, you can run our unit test suite with:

make test

Note: the importcsv test requires a UTF-8 environment to run successfully.

Building using the Python release-tool

Starting with version 2.7.11, KeePassXC ships with a python release-tool.py that automates building release packages from a specified release tag (the --version parameter). To see a help listing for the command, download and unpack the source code as described in the Linux section, change into the source directory and run ./release-tool.py build:

KeePassXC Release Preparation Tool
Copyright (C) 2016-2026 KeePassXC Team <https://keepassxc.org/>

usage: release-tool.py build [-h] [-s SRC_DIR] [-t TAG_NAME] [-o OUTPUT_DIR] [-g CMAKE_GENERATOR] [-i INSTALL_PREFIX] [--snapshot] [--use-system-deps] [-j PARALLELISM] [-y] [--with-tests] [--minimal] [--build-qt] [--override-version OVERRIDE_VERSION] [-p {x86_64,amd64,aarch64,arm64}] [-d DOCKER_IMAGE] [-a]
                             [--macos-target MACOSX_DEPLOYMENT_TARGET] [--sign] [--sign-identity SIGN_IDENTITY] [--notarize] [--keychain-profile KEYCHAIN_PROFILE] [-c ...]
                             version

positional arguments:
  version               Release version number or name.

options:
  -h, --help            show this help message and exit
  -s SRC_DIR, --src-dir SRC_DIR
                        Source directory.
  -t TAG_NAME, --tag-name TAG_NAME
                        Name of the tag to check out (default: same as version).
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Build output directory (default: release.
  -g CMAKE_GENERATOR, --cmake-generator CMAKE_GENERATOR
                        Override default CMake generator.
  -i INSTALL_PREFIX, --install-prefix INSTALL_PREFIX
                        Build install prefix (default: /usr/local).
  --snapshot            Build snapshot from current HEAD.
  --use-system-deps     Use system dependencies instead of vcpkg.
  -j PARALLELISM, --parallelism PARALLELISM
                        Build parallelism (default: 12).
  -y, --yes             Bypass confirmation prompts.
  --with-tests          Build and run tests.
  --minimal             Build with minimal feature set.
  --build-qt            Build Qt6 dependency.
  --override-version OVERRIDE_VERSION
                        Override displayed version number.
  -p {x86_64,amd64,aarch64,arm64}, --platform-target {x86_64,amd64,aarch64,arm64}
                        Build target platform (default: arm64).
  -d DOCKER_IMAGE, --docker-image DOCKER_IMAGE
                        Build for Linux in the given Docker image (overrides --use-system-deps).
  -a, --appimage        Build a Linux AppImage.
  --macos-target MACOSX_DEPLOYMENT_TARGET
                        macOS deployment target version (default: 12).
  --sign                Sign binaries prior to packaging.
  --sign-identity SIGN_IDENTITY
                        Apple Developer identity name used for signing binaries (default: ask).
  --notarize            Notarize signed file(s).
  --keychain-profile KEYCHAIN_PROFILE
                        Read Apple credentials for notarization from a keychain (default: notarization-creds).
  -c ..., --cmake-opts ...
                        Additional CMake options (no other arguments can be specified after this).

The build subcommand automates the compilation and packaging steps described above and also performs a few more packaging steps such as exporting a source tarball and building an AppImage on Linux.

When not specified otherwise, it will create a directory called release where it moves the built artefacts.

Building inside a Docker container

The release-tool also allows you to build KeePassXC inside a Docker container on Linux. This is important when building a cross-platform AppImage. To pull the needed Docker image, run

docker pull keepassxc/keepassxc-ci

This will pull the latest Docker image from the Docker hub registry. You can then start the build process with

python release-tool.py build <VERSION> --appimage -d ghcr.io/keepassxreboot/keepassxc-ci-docker:noble-qt6.4

Important: rebuild the docker image regularly with --no-cache to ensure it has the latest security updates!