Required Dependencies
KeePassXC supports the following Operating Systems:
- Windows 10 and 11
- MacOS 11.0+
- Linux (Ubuntu 18.04+/Debian Buster+/Mint 19+/Fedora 33+/RHEL 7+/CentOS 7+/Arch)
The following build tools must exist in your PATH:
- cmake (>= 3.10.0)
- make (>= 4.2) or ninja (>= 1.10)
- g++ (>= 4.9) or clang++ (>= 6.0)
- asciidoctor (>= 2.0)
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. For example: cmake -DWITH_XC_AUTOTYPE=ON -DWITH_XC_NETWORKING=OFF -DWITH_XC_KEESHARE=ON ..
-DWITH_XC_AUTOTYPE=[ON|OFF] Enable/Disable Auto-Type (default: ON)
-DWITH_XC_YUBIKEY=[ON|OFF] Enable/Disable YubiKey HMAC-SHA1 authentication support (default: OFF)
-DWITH_XC_BROWSER=[ON|OFF] Enable/Disable KeePassXC-Browser extension support (default: OFF)
-DWITH_XC_NETWORKING=[ON|OFF] Enable/Disable Networking support (e.g., favicon downloading) (default: OFF)
-DWITH_XC_SSHAGENT=[ON|OFF] Enable/Disable SSHAgent support (default: OFF)
-DWITH_XC_FDOSECRETS=[ON|OFF] (Linux Only) Enable/Disable Freedesktop.org Secrets Service support (default:OFF)
-DWITH_XC_KEESHARE=[ON|OFF] Enable/Disable KeeShare group synchronization extension (default: OFF)
-DWITH_XC_ALL=[ON|OFF] Enable/Disable compiling all plugins above (default: OFF)
-DWITH_XC_UPDATECHECK=[ON|OFF] Enable/Disable automatic updating checking (requires WITH_XC_NETWORKING) (default: ON)
-DWITH_TESTS=[ON|OFF] Enable/Disable building of unit tests (default: ON)
-DWITH_GUI_TESTS=[ON|OFF] Enable/Disable building of GUI tests (default: OFF)
-DWITH_DEV_BUILD=[ON|OFF] Enable/Disable deprecated method warnings (default: OFF)
-DWITH_ASAN=[ON|OFF] Enable/Disable address sanitizer checks (Linux / macOS only) (default: OFF)
-DWITH_COVERAGE=[ON|OFF] Enable/Disable coverage tests (GCC only) (default: OFF)
-DWITH_APP_BUNDLE=[ON|OFF] Enable Application Bundle for macOS (default: ON)
-DKEEPASSXC_BUILD_TYPE=[Snapshot|PreRelease|Release] Set the build type to show/hide stability warnings (default: "Snapshot")
-DKEEPASSXC_DIST_TYPE=[Snap|AppImage|Other] Specify the distribution method (default: "Other")
-DOVERRIDE_VERSION=[X.X.X] Specify a version number when building. Used with snapshot builds (default: "")
-DGIT_HEAD_OVERRIDE=[XXXXXXX] Specify the 7 digit git commit ref for this build. Used with distribution builds (default: "")
Building Manually
1. Set up your build environment
Use the following guides to setup your build environment:
2. Building
Linux
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. If you would like to run tests after building, add -DWITH_TESTS=ON -DWITH_GUI_TESTS=ON before the ..
mkdir build
cd build
cmake -DWITH_XC_ALL=ON -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_TOOLCHAIN_FILE=${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake \
-DVCPKG_TARGET_TRIPLET=arm64-osx-dynamic-release
-DWITH_XC_ALL=ON ..
make -j8 package
Make sure that ${VCPKG_ROOT} points to your vcpkg installation. Omit -DCMAKE_TOOLCHAIN_FILE and -DVCPKG_TARGET_TRIPLET if you installed dependencies via Homebrew.
Replace arm64-osx-dynamic-release with 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.
If you installed Qt5 via Homebrew and CMake fails to find your Qt installation, you can specify it manually by adding the following parameter:
-DCMAKE_PREFIX_PATH=$(brew --prefix qt5)/lib/cmake
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. If instead, you are using Msys2, open a MSYS2 MinGW terminal (not MSYS2 MSYS which is the default).
Download and unpack the source code as described in the Linux section. To build KeePassXC with MSVC, open a PowerShell, change into the source code directory, and run:
mkdir build
cd build
cmake -G Ninja -DWITH_XC_ALL=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake ..
ninja -j8
Make sure that -DCMAKE_TOOLCHAIN_FILE points to the correct path of your vcpkg installation.
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
python release-tool.py
The release-tool has several subcommands. Only the build subcommand is relevant to non-maintainers. You can get help for each by adding -h after the subcommand.
python release-tool.py <SUBCOMMAND> -h
build subcommand
$ python release-tool.py build -h
KeePassXC Release Preparation Tool
Copyright (C) 2016-2025 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] [-p {amd64,arm64}]
[--sign] [--sign-cert SIGN_CERT] [-c ...]
version
positional arguments:
version Release version number or name.
options:
-h, --help show this help message and exit
-s, --src-dir SRC_DIR
Source directory.
-t, --tag-name TAG_NAME
Name of the tag to check out (default: same as version).
-o, --output-dir OUTPUT_DIR
Build output directory (default: release.
-g, --cmake-generator CMAKE_GENERATOR
Override default CMake generator.
-i, --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
Build parallelism (default: 22).
-y, --yes Bypass confirmation prompts.
--with-tests Build and run tests.
-p, --platform-target {amd64,arm64}
Build target platform (default: amd64).
--sign Sign binaries prior to packaging.
--sign-cert SIGN_CERT
SHA1 fingerprint of the signing certificate (optional).
-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 containing the build directory, a source tarball and the packaged binary bundles. On Linux, there will also be a directory ending with .AppDir inside the release directory, containing stripped versions of all the compiled binaries without additional dependencies.
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 keepassxc/keepassxc-ci
Important: rebuild the docker image regularly with --no-cache to ensure it has the latest security updates!
Copyright (C) 2016-2025 KeePassXC Team