Set up Build Environment on macOS

Note: This is only a one-time setup guide. For actually building KeePassXC, please refer to our build guide.

Install the build toolchain

First, install Xcode from the AppStore and run

xcode-select --install

in a terminal to install the Xcode CLI tools. Next, install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

(or use the pkg installer if you dislike curl | bash).

Use Homebrew to install the required build tools:

brew install cmake asciidoctor

Install build dependencies

To install the actual build dependencies, there are two options:

1. Via Homebrew (faster, but suitable only for local builds).
2. Via vcpkg (much slower, but suitable for distribution).

Option 1: Install build dependencies via Homebrew

Open a terminal and run:

brew install qt@5 argon2 botan qrencode readline minizip

Option 2: Install build dependencies via vcpkg

Set up vcpkg in a location of your choosing:

git clone https://github.com/Microsoft/vcpkg.git && ./vcpkg/bootstrap-vcpkg.sh

Install pkg-config and (optionally) the vcpkg stub package from Homebrew:

brew install pkg-config vcpkg

If you installed the vcpkg stub package, set the VCPKG_ROOT environment variable to your install location. You can then run the vcpkg command from anywhere, given that Homebrew is in your PATH. Otherwise, call the vcpkg binary with its full path.

Finally, compile and install the actual build dependencies using the arm64-osx-dynamic or x64-osx-dynamic triplets (depending on your architecture). The default arm64-osx or x64-osx triplets will compile Qt as a static library, which will give you lots of headaches.

Apple Silicon:

vcpkg --triplet=arm64-osx-dynamic install argon2 botan minizip qt5 qt5-svg qt5-tools qt5-imageformats \
    qt5-macextras qt5-translations readline zlib libqrencode

Intel Mac:

vcpkg --triplet=x64-osx-dynamic install argon2 botan minizip qt5 qt5-svg qt5-tools qt5-imageformats \
    qt5-macextras qt5-translations readline zlib libqrencode

Afterwards, add the include and lib directories under $VCPKG_ROOT/installed/<triple> to your compiler and linker path or set -DCMAKE_PREFIX_PATH when compiling KeePassXC. You also need to set the runtime path (DYLD_LIBRARY_PATH) accordingly.

Hint: If you have custom INCLUDE or CPATH variables set, make sure, . is not part of your include path and the path variables contain no empty segmemts (which can happen easily if you construct them like export INCLUDE="/some/include/path:${INCLUDE}") or else you will see strange compilation errors.

Update your environment regularly

Homebrew:

brew update && brew upgrade

vcpkg:

cd vcpkg && git pull && ./vcpkg update