Is KeePassXC safe to sync to cloud storage like Dropbox or Nextcloud?

Yes. The .kdbx file is fully encrypted with AES-256 before it ever leaves your machine. An attacker who steals the file still needs your master password (and key file or YubiKey if configured) to read anything. Sync it wherever is convenient.

What is the difference between YubiKey Challenge-Response and TOTP in KeePassXC?

Challenge-Response requires the physical YubiKey to be connected during database unlock — the key performs a cryptographic operation the software alone cannot replicate. TOTP codes in KeePassXC are just stored secrets that generate time-based codes; they provide no hardware binding.

Can I use KeePassXC without a graphical desktop, for example on a server?

Yes. KeePassXC ships a CLI tool called keepassxc-cli that can look up, add, and manage entries entirely from the terminal. Run keepassxc-cli --help for available commands.

Does browser autofill work on Wayland without XWayland?

Yes, browser integration (form fill via the extension) works natively on Wayland. The Autotype feature, which synthesizes keyboard events globally, requires XWayland because Wayland compositors block cross-application input injection by design.

What happens if I forget the master password to my database?

The database cannot be recovered — that is the point of AES-256 encryption. There is no backdoor and no recovery email. Maintain at least two backups of the .kdbx file and store your master password somewhere secure, such as written down in a physically locked location.

Install KeePassXC for Local Password Management

KeePassXC is a community-maintained, offline-first password manager. It stores credentials in an encrypted .kdbx database file that never leaves your machine unless you choose to sync it. It supports browser autofill, SSH key management, system secret service integration, and hardware security keys — all without a cloud account. This guide walks through installation, initial setup, and the features that make KeePassXC genuinely useful beyond a basic password vault.

Installation

Debian and Ubuntu

KeePassXC is in the official repositories, but the version there often lags behind. The upstream PPA gives you a more recent release.

sudo add-apt-repository ppa:phoerious/keepassxc
sudo apt update
sudo apt install keepassxc

Fedora and RHEL/Rocky

# Fedora
sudo dnf install keepassxc

# Rocky Linux 9 / RHEL 9 — enable EPEL first
sudo dnf install epel-release
sudo dnf install keepassxc

Arch Linux

sudo pacman -S keepassxc

Verify the binary is present and check the version before continuing:

keepassxc --version
# Output will look similar to: KeePassXC 2.7.9

Creating Your First Database

Launch KeePassXC from your application menu or run keepassxc in a terminal. Click Create new database.

Name and description — choose something meaningful; this is metadata stored inside the file.
Encryption settings — leave the algorithm at AES-256. Increase the decryption delay to at least 1 second by adjusting the benchmark slider. This makes brute-force attacks significantly slower without noticeably impacting your daily unlock time.
Credentials — set a strong master password. Optionally add a key file (a random binary blob stored separately) for two-factor protection. Keep any key file backed up; lose it and the database is permanently locked.

Save the .kdbx file somewhere deliberate — a synced folder (Nextcloud, Syncthing) if you want multi-device access, or a local encrypted volume if you want maximum isolation.

Browser Integration

KeePassXC communicates with Firefox and Chromium-based browsers through a native messaging host, not a cloud relay. The browser extension connects directly to the running KeePassXC process over a local socket.

Step 1 — Enable the browser integration in KeePassXC

# No terminal step needed — use the GUI:
# Tools → Settings → Browser Integration
# Check "Enable browser integration" and tick your browser(s)

Step 2 — Install the browser extension

Firefox: KeePassXC-Browser on AMO
Chrome / Chromium / Brave: KeePassXC-Browser on the Web Store

Step 3 — Pair the extension

Click the KeePassXC extension icon in your browser toolbar and click Connect. KeePassXC will prompt you to name the connection — use something like firefox-laptop. The extension will now autofill credentials when the database is unlocked. If KeePassXC is closed, the extension shows a disconnected status rather than silently failing.

Wayland note: Browser integration works under Wayland without any extra steps in KeePassXC 2.7+. Autotype (the keyboard-emulation feature) requires XWayland because Wayland compositors do not allow applications to synthesize global keyboard input.

SSH Agent Integration

KeePassXC can act as an SSH agent, serving private keys stored as attachments in the database. This replaces ssh-add for keys you want loaded automatically on database unlock.

Enable the SSH agent

# Tools → Settings → SSH Agent → Enable SSH Agent integration
# KeePassXC will communicate with the running ssh-agent socket.

Ensure a real SSH agent is already running. On most modern desktops, ssh-agent is started by your login session. Confirm:

echo $SSH_AUTH_SOCK
# Should return a path like /run/user/1000/keyring/ssh or similar

If the variable is empty, start an agent manually or let your desktop session handle it. GNOME Keyring and KDE Wallet both provide an SSH agent socket; you can keep them running alongside KeePassXC's agent integration — KeePassXC adds keys to whichever agent the socket points to.

Store an SSH key in the database

Create or open an entry for the relevant server.
Go to the Advanced tab and attach your private key file (e.g., id_ed25519).
Go to the SSH Agent tab within the entry, select the attachment, and enable Add key to agent when database is opened/unlocked.

After saving, lock and unlock the database. Verify the key loaded:

ssh-add -l
# Output will list the fingerprint of your stored key

Secret Service Integration

Applications on Linux that need to store secrets — GNOME Online Accounts, Chromium's keyring, libsecret consumers — look for a D-Bus service implementing the freedesktop Secret Service API. KeePassXC can provide this, replacing GNOME Keyring or KWallet for those consumers.

# Tools → Settings → Secret Service Integration
# Enable "Enable KeePassXC Secret Service integration"
# Assign a database group that will back the secret service

Important: If GNOME Keyring or KWallet is already running as the secret service provider, you must disable them first, or they will claim the D-Bus name before KeePassXC can. On GNOME:

systemctl --user mask gnome-keyring-daemon.service gnome-keyring-daemon.socket

Log out and back in. KeePassXC must be set to start automatically (see below) so it can register the secret service at login.

Autostart KeePassXC with systemd

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/keepassxc.service << 'EOF'
[Unit]
Description=KeePassXC password manager
After=graphical-session.target

[Service]
ExecStart=/usr/bin/keepassxc
Restart=on-failure

[Install]
WantedBy=graphical-session.target
EOF

systemctl --user enable --now keepassxc.service

YubiKey Integration

KeePassXC supports YubiKey Challenge-Response (HMAC-SHA1) as a second factor for database unlock. This is different from TOTP — it requires physical presence of the key. The YubiKey must be programmed with a secret in slot 1 or slot 2 before use.

Program the YubiKey (if not already done)

# Debian/Ubuntu
sudo apt install yubikey-manager

# Fedora
sudo dnf install yubikey-manager

# Arch
sudo pacman -S yubikey-manager

# Program slot 2 with a random HMAC-SHA1 secret
ykman otp chalresp --generate 2

Back up the secret before using it to protect a database. If the YubiKey is lost or reset without a backup, the database cannot be opened. Use ykman otp export or the YubiKey Personalization Tool to save the configuration.

Add YubiKey to the database credentials

Open database settings: Database → Database Security.
Click Add additional protection → Add YubiKey Challenge-Response.
Select the slot that was programmed, then click OK.

From this point, unlocking the database requires both the master password and a physical tap or touch on the YubiKey during the challenge-response exchange. On systems without the ykpers library, install it:

# Debian/Ubuntu
sudo apt install libykpers-1-1

# Fedora
sudo dnf install ykpers

Verification

Run through this checklist after setup:

Lock and reopen the database — confirm the master password (and YubiKey if configured) are both required.
Navigate to a login page in your browser — confirm the extension fills credentials without manual copy-paste.
Run ssh-add -l immediately after unlocking the database to confirm SSH keys appear.
Run secret-tool lookup test dummy 2>&1 — if KeePassXC is the active secret service provider and the database is unlocked, it will respond (even with an empty result) rather than error with No such secret.

Troubleshooting

Browser extension shows "KeePassXC is not running" — the browser integration socket is only created when KeePassXC is open. Start the application; the extension reconnects automatically.
SSH keys not loading — confirm $SSH_AUTH_SOCK is set and points to a writable socket. GNOME Keyring may be claiming the agent role; check with ps aux | grep gnome-keyring.
YubiKey not detected — check USB udev rules. Add yourself to the plugdev group or install the official udev rules: sudo apt install yubikey-manager does this on Debian/Ubuntu. Verify with ykman list.
Secret service conflicts — run dbus-send --session --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames and look for org.freedesktop.secrets to see which process owns it.