Connecting KeePassXC and Waterfox on Linux

Today, I was setting up Waterfox, a Firefox fork without Mozilla’s debatable AI integrations. I use KeePassXC for passwords and passkeys, for which I had to install the browser extension. Unfortunately, Waterfox and KeePassXC do not work together out of the box.

A quick search sent me to a Github discussion that eventually led me to this helpful section of the KeePassXC docs. There is also a wonderful guide for all sorts of browsers in the Troubleshooting Guide.

Here is a TL;DR of what I ended up doing. This is more of a rough quick-start and a note for my later self. Please refer to the official docs for all details.

TL;DR

Install Waterfox, but not as a snap or flatpak as the sandboxing prevents it from talking to the password manager. Install the KeePassXC browser extension.

Install KeePassXC. Go to “Settings → Browser Integration.” Tick “Enable Browser Integration.” Go to the “Advanced” tab. Change the config location to ~/.waterfox/native-messaging-hosts. Confirm with “OK.”

In Waterfox, click on the KeePassXC extension icon (either in the icon bar or via the jigsaw icon). Click on “Reload”. It should now show the option to connect to the database.

Just in case …

If Waterfox does not recognize KeePassXC, you can debug the file location where the browser extension expects KeePassXC’s config. Start the following strace command, then click on the KeePassXC extension icon in Waterfox and click on “Reload”.

me@laptop:~> sudo strace -f -p $(pgrep waterfox) -e trace=file -s 200 2>&1 |   grep -i -E 'keepass|native-messaging-hosts|kdbx'
[pid 83822] openat(AT_FDCWD, "/home/me/.waterfox/native-messaging-hosts/org.keepassxc.keepassxc_browser.json", O_RDONLY) = -1 ENOENT (No such file or directory)
[pid 83822] openat(AT_FDCWD, "/usr/lib/waterfox/native-messaging-hosts/org.keepassxc.keepassxc_browser.json", O_RDONLY) = -1 ENOENT (No such file or directory)

This has been suggested on the Github issue page. More troubleshooting information can be found on KeePassXC’s Github.

These instructions have last been checked on 1 March 2026 using openSUSE Tumbleweed 20260223, Waterfox 6.6.9, and KeePassXC 2.7.11.