Building KeePassXC
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.
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: "")
Use the following guides to setup your build environment:
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
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).
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 -DWITH_XC_ALL=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake ..
make -j8 package
Make sure that -DCMAKE_TOOLCHAIN_FILE points to the correct path of your vcpkg installation.
If you build with Msys2, omit -DCMAKE_TOOLCHAIN_FILE and -DVCPKG_TARGET_TRIPLET altogether and add -G "MSYS Makefiles" instead.
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.
Starting with version 2.1.1, KeePassXC ships with a release-tool 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 help
The release-tool has three subcommands. You can get help for each by running
./release-tool help <COMMAND>
Sub commands are:
$ ./release-tool help build
KeePassXC Release Preparation Helper
Copyright (C) 2017 KeePassXC Team <https://keepassxc.org/>
Usage: release-tool build [options]
Build and package binary release from sources
Options:
-v, --version Release version number or name (required)
-a, --app-name Application name (default: 'KeePassXC')
-s, --source-dir Source directory (default: '.')
-o, --output-dir Output directory where to build the release
(default: 'release')
-t, --tag-name Release tag to check out (defaults to version number)
-b, --build Build sources after exporting release
-d, --docker-image Use the specified Docker image to compile the application.
The image must have all required build dependencies installed.
This option has no effect if --build is not set.
--container-name Docker container name (default: 'keepassxc-build-container')
The container must not exist already
-c, --cmake-options Additional CMake options for compiling the sources
--compiler Compiler to use (default: 'g++')
-m, --make-options Make options for compiling sources (default: '-j8')
-i, --install-prefix Install prefix (default: '/usr/local')
-p, --plugins Space-separated list of plugins to build
(default: autotype)
-n, --no-source-tarball Don't build source tarball
-h, --help Show this help
$ ./release-tool help merge
KeePassXC Release Preparation Helper
Copyright (C) 2017 KeePassXC Team <https://keepassxc.org/>
Usage: release-tool merge [options]
Merge release branch into main branch and create release tags
Options:
-v, --version Release version number or name (required)
-a, --app-name Application name (default: 'KeePassXC')
-s, --source-dir Source directory (default: '.')
-g, --gpg-key GPG key used to sign the merge commit and release tag,
leave empty to let Git choose your default key
(default: '')
-r, --release-branch Source release branch to merge from (default: 'release/VERSION')
--target-branch Target branch to merge to (default: 'master')
-t, --tag-name Override release tag name (defaults to version number)
-h, --help Show this help
$ ./release-tool help sign
KeePassXC Release Preparation Helper
Copyright (C) 2017 KeePassXC Team <https://keepassxc.org/>
Usage: release-tool sign [options]
Sign previously compiled release packages
Options:
-f, --files Files to sign (required)
-g, --gpg-key GPG key used to sign the files (default: 'CFB4C2166397D0D2')
-h, --help Show this help
If you are not a KeePassXC maintainer, the only interesting command for you is release-tool build. This will automate the compilation and packaging steps described above and also perform 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 release-bin inside the release directory, containing stripped versions of all the compiled binaries without additional dependencies.
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
./release-tool build -v VERSION --appimage -d keepassxc/keepassxc-ci
Important: rebuild the image regularly with --no-cache to ensure it has the latest security updates!
Copyright (C) 2016-2023 KeePassXC Team