Documentation and FAQ

Documentation and Quickstart

For getting you started with KeePassXC, we have a short Quickstart Guide.

More comprehensive in-depth documentation, build/install instructions and many other guides can be found in the Wiki.

Contribute

You can contribute to the project by…

Frequently Asked Questions

Questions

General
Security
AppImage and Snap package
YubiKey
Browser integration
SSH Agent
Platform-specific
Development

Answers

General
Why KeePassXC instead of KeePassX?
KeePassX is an amazing password manager, but hasn't seen much active development for quite a while. Many good pull requests were never merged and the original project is missing some features which users can expect from a modern password manager. Hence, we decided to fork KeePassX to continue its development and provide you with everything you love about KeePassX plus many new features and bugfixes.
Why KeePassXC instead of KeePass?
KeePass is a very proven and feature-rich password manager and there is nothing fundamentally wrong with it. However, it is written in C# and therefore requires Microsoft's .NET platform. On systems other than Windows, you can run KeePass using the Mono runtime libraries, but you won't get the native look and feel which you are used to.
KeePassXC, on the other hand, is developed in C++ and runs natively on all platforms giving you the best-possible platform integration.
Which password database formats are compatible with KeePassXC?
KeePassXC currently uses the KeePass 2.x (.kdbx) password database format as its native file format in versions 3.1 and 4. Database files in version 2 can be opened, but will be upgraded to a newer format. KeePass 1.x (.kdb) databases can be imported into a .kdbx file, but this process is one-way.
Why is there no cloud synchronization feature built into KeePassXC?
Cloud synchronization with Dropbox, Google Drive, OneDrive, ownCloud, Nextcloud etc. can be easily accomplished by simply storing your KeePassXC database inside your shared cloud folder and letting your desktop synchronization client do the rest. We prefer this approach, because it is simple, not tied to a specific cloud provider and keeps the complexity of our code low.
Does KeePassXC support (KeePass2) plugins?
No, KeePassXC does not support plugins at the moment. We are thinking about providing some kind of plugin infrastructure or external API in the future, but cannot specify how it will work or when it will be ready.
How can I add additional word lists to the passphrase generator?
You can add additional word lists to the passphrase generator by copying the word list file to the share/wordlists folder inside your KeePassXC installation directory and then restarting KeePassXC.
On Linux, the default install location is /usr/share/keepassxc, on macOS it's /Applications/KeePassXC.app/Contents/Resources and on Windows C:\Program Files\KeePassXC (or C:\Program Files (x86)\KeePassXC for 32-bit).
Security
How can I migrate my database to KDBX 4?
Go to Database / Database settings, select Encryption and choose a Key Derivation Function that is marked with KDBX 4, then save the database.
KeePassXC allows me to store my TOTP secrets. Doesn't this alleviate any advantage of two-factor authentication?
Yes. But only if you store them in the same database as your password. We believe that storing both together can still be more secure than not using 2FA at all, but to maximize the security gain from using 2FA, you should always store TOTP secrets in a separate database, secured with a different password, possibly even on a different computer.
Why would I use a password manager? Isn't it totally insecure to use one password for everything?
Password reuse and simple, easy-to-guess passwords are the biggest problems when using online services. If one service gets compromised (either by guessing your password or by exploiting a security vulnerability in the service's infrastructure), an attacker may gain access to all of your other accounts. But using different passwords for all websites is difficult without a way of storing them somewhere safe. Especially with arbitrary password rules for various services, it becomes increasingly hard to use both strong and diverse passwords. KeePassXC stores your passwords for you in an encrypted database file, so you only need to remember one master password. Of course, the security of all your services depends on the strength of your master password now, but with a sufficiently strong password, the password database should be infeasible to crack. The database is encrypted with either the industry-standard AES256 or the Twofish block cipher and the master password is strengthened by a configurable number of key transformations to harden it against brute force attacks. Additionally, you can use a key file filled with an arbitrary number of random bytes or a YubiKey to further enhance your master key.
Has KeePassXC ever had an external security audit? Why not?
At the time of writing, No. Having a third-party security audit comes with a considerable price and at the moment, KeePassXC is a purely community-driven project. There is no company or business behind KeePassXC and we have other expenses. We receive some donations, but those are not enough to finance an audit. Maybe you can beg OSTIF or OTF for funding a KeePassXC audit.
In any case, keep in mind that:
  • An audit is not a 100% proof that a software is safe and secure. Some flaws can be overlooked even by the best auditors.
  • An audit is valid only for a “snapshot” of the code. If new code is added, new vulnerabilities can be introduced.
I see that KeePassXC requires network access. What for?
KeePassXC needs network access for downloading website icons (favicons) for password entries and for providing KeePassHTTP-compatible browser extensions with access to your database. Both features are optional and opt-in. KeePassXC will never access any network resource without your explicit prior consent. If you don't use either of these features, you may also compile KeePassXC without any networking code (see next question).
Can I get a KeePassXC version without any networking code?
Yes, you can compile KeePassXC without any networking code. Simply configure CMake with -DWITH_XC_NETWORKING=OFF (see Building KeePassXC).
AppImage and Snap package
How do I execute an AppImage?
The AppImage is a self-contained executable archive, comparable to an Android APK or macOS DMG. To execute it, simply give the downloaded *.AppImage file execution permissions: 
chmod +x ./KeePassXC-*.AppImage
After that you can execute it either from the terminal or by double clicking it just like any other program.
What systems can I use the AppImage or Snap package on?
The AppImage should run out of the box on almost any moderately modern Linux distribution. The Snap is supported on all systems, which have snapd installed. This is primarily Ubuntu, but also Debian, Fedora, OpenSUSE, Arch Linux and many more. For a full list and more information visit snapcraft.io. Note that not all systems that can run Snaps also support confinement via AppArmor.
How do I use the KeePassXC CLI tool with the AppImage?
Starting with version 2.2.2, you can run the KeePassXC CLI tool from the AppImage by executing it with the cli argument: 
./KeePassXC-*.AppImage cli
Why doesn't my theme work?
Since Snaps and AppImages are self-contained and mostly isolated from your system, they cannot know what theme you are currently running. This is a known issue with both Snaps and AppImages.
How do I get my YubiKey to work with the Snap?
Due to a Snap's isolation and security settings, you must manually enable the raw-usb interface in order to use your YubiKey. Issue the following command from a terminal to enable this interface: 
sudo snap connect keepassxc:raw-usb core:raw-usb
Why can't I see anything outside my home directory?
Due to Snap's isolation and security settings, you cannot access any files outside your home directory. Furthermore, you cannot access any hidden files within your home directory. The only exception is mounted USB drives, but you must type in /media/ into the file open dialog to see them.
YubiKey
Does KeePassXC support two-factor authentication (2FA) with YubiKeys?
Yes and no. KeePassXC supports YubiKeys for securing a database, but strictly speaking, it's not two-factor authentication. KeePassXC generates a challenge and uses the YubiKey's response to this challenge to enhance the encryption key of your database. So in a sense, it makes your password stronger, but technically it doesn't qualify as a separate second factor, since the expected response doesn't change every time you try to decrypt your database. It does, however, change every time you save your database.
How do I configure my YubiKey for use with KeePassXC?
To use a YubiKey for securing your KeePassXC database, you have to configure one of your YubiKey slots for HMAC-SHA1 Challenge Response mode (see this video for how to do this). Once your YubiKey is set up, open your database in KeePassXC, go to File / Change master key, enable Challenge Response and then save the database.
Important: Always make a copy of the secret that is programmed into your YubiKey while you configure it for HMAC-SHA1 and store it in a secure location. If you lose or brick the key or accidentally reprogram it with a different secret, you will permanently lose access to your database!
When I use KeeChallenge with KeePass2, it creates an extra file. Why do I have no such file when using KeePassXC?
Our implementation differs from how KeeChallenge handles YubiKeys. KeeChallenge uses the HMAC secret directly to enhance the database. To make this work, they need to store the secret in a side-car file, encrypted with the response of a challenge-response pair that is calculated ahead of time. In KeePassXC, we do not require any knowledge of the HMAC secret. We use the database's master key as challenge and then use the response to encrypt the database. That way we do not need an extra file and also gain the advantage that the required response changes every time you save the database, which resembles actual two-factor authentication more closely.
When I secure my database in KeePass2 with a YubiKey, I can't open it in KeePassXC (or vice versa), why?
Due to the fact that our YubiKey implementation differs from KeeChallenge's, they are inherently incompatible (see question above). If you need compatibility between KeePass2 and KeePassXC, you cannot use YubiKeys at the moment.
Why only HMAC-SHA1? Why not FIDO-U2F or TOTP?
Both FIDO-U2F and TOTP require a dynamic component (i.e., a counter or timestamp) for successful authentication. This is perfect for authenticating at an online service, but doesn't work for an offline database which needs to be encrypted with a fixed key. HMAC-SHA1, on the other hand, can be computed ahead of time as it only needs a fixed secret and no dynamic component of any kind.
But the feature list says KeePassXC supports TOTP. I am confused.
We do support generation of timed one-time passwords (TOTP), but do not (and cannot) support it for securing your KeePassXC database. KeePassXC allows you to store TOTP secrets for online services inside a database and generates the corresponding timed one-time passwords for you. For TOTP, see also the question KeePassXC allows me to store my TOTP secrets. Doesn't this alleviate any advantage of two-factor authentication?
What happens if I break my YubiKey? Can I create backup keys?
You should always make a copy of the HMAC secret that is stored on the YubiKey and keep it in a secure location. This can be an analog paper copy, but since the YubiKey personalization tool allows you to program a custom secret into the key, you may as well program a second key with the same secret.
Can I register multiple YubiKeys with my KeePassXC database?
You can only use a single secret for encrypting the database. So you can use multiple YubiKeys, but they all have to be programmed with the same secret (see question above).
Browser integration
Does KeePassXC support browser extensions?
Yes. KeePassXC supports KeePassHTTP-Connector as a legacy browser integration and a newer extension KeePassXC-Browser. You can download KeePassXC-Browser for Mozilla Firefox and Google Chrome / Chromium / Vivaldi. Firefox ESR (52.x) is supported, but the following features are disabled because of WebExtension API limitations:
  • Showing context menus on password fields (menus.ContextType)
  • HTTP Auth support (webRequest.onAuthRequired)
How do I connect browser extensions with KeePassXC?
You can enable Browser Integration (KeePassXC-Browser) or Legacy Browser Integration (KeePassHTTP-Connector) from KeePassXC settings. A guide for KeePassHTTP-Connector is available here. See the page How to connect KeePassXC-Browser with KeePassXC for more detailed information for the new Browser Integration. For troubleshooting see the following wiki page.
How does the new browser integration differ from the old?
Older TCP socket based KeePassHTTP has been replaced with native messaging, and traffic is encrypted with libsodium's Public-key authenticated encryption. Native messaging ensures that KeePassXC-Browser can only communicate with a specified application. Also, it is possible to use multiple browsers simultaneously. For more detailed info, please see the project's GitHub page.
Where are the KeePassXC-Browser settings on Ubuntu 14.04 Trusty?
KeePassXC-Browser requires Qt 5.3, which is not available on Ubuntu 14.04 Trusty. If you need browser integration, you need to use our AppImage release or upgrade to Ubuntu 16.04 Xenial or newer.
SSH Agent
How does the SSH Agent work?
The SSH Agent feature is supported on all target platforms (Linux, macOS and Windows) and it acts as a client for an existing agent. It can automatically add SSH keys from your KeePassXC database to a running SSH agent when unlocked and remove them when locked.

On Linux, most desktops are already running an agent without any set up required.
On Windows, you need to have Pageant running. It is part of the PuTTY suite.
On macOS, ssh-agent is running by default and no further setup is required.
What SSH key types are supported?
Most SSHv2 key types are supported (DSA, RSA and Ed25519), including encrypted keys. ECDSA keys are only supported with the new OpenSSH file format. 3DES-encrypted keys are not supported and we highly recommend upgrading them for external storage or store them decrypted inside the database.

SSHv1 keys are not supported.
PuTTY format key files (.ppk) are not supported. You can use PuTTY Key Generator (puttygen.exe) to convert your keys to OpenSSH format.
RFC4716 format key files are not supported.
Why are the agent buttons greyed out / why doesn't it work?
On Linux or macOS, you need to have ssh-agent running and the SSH_AUTH_SOCK environment variable available for KeePassXC at launch. Arch Linux wiki has a generic guide how to manually run ssh-agent if it's not already set up. Sometimes other applications like GNOME Keyring or gpg-agent already provide a compatible agent that also works with KeePassXC.
On Windows, Pageant needs to be running, see How does the SSH Agent work?.
How do I set up a passphrase for encrypted keys?
The SSH Agent feature uses the entry password field as the decryption key.
Why does the public key (seem to) have no comment?
When using normal DSA or RSA keys, the private key file does not contain any embedded text. In that case, the entry username field is used as the public key comment. It is also sent to the agent when adding a key and is visible in the agent when listing keys.
If you are using Ed25519 keys or have converted your old key to the new OpenSSH file format, the comment is embedded in the key file which is then used by KeePassXC. You can use ssh-keygen to modify the comment.
I'm already using KeeAgent, is KeePassXC compatible with it?
Yes, mostly. KeeAgent supports more key types and provides a custom agent, but otherwise you can use the same database with KeeAgent and KeePassXC.
Why is Pageant refusing my keys?
Pageant does not support confirm-on-use or automatic removal of key after a timeout. There doesn't seem to be any alternative to Pageant for Windows that supports both of them.
Why is OpenSSH ssh-agent refusing my keys?
If you are using confirm-on-use option for your keys, ssh-agent needs to have a "ssh-askpass" program available.
On Linux it depends on your distribution and desktop environment how to install and configure one as there are several available.
On macOS, you need a third party program like theseal/ssh-askpass.
I'm getting protocol or connection errors, what's wrong?
If you are using GNOME Keyring, it is known to be buggy and the SSH Agent implementation fairly incomplete prior to release 3.27.92. You are encouraged to use OpenSSH ssh-agent if you are stuck with an older version.
Known limitations of older versions include no support for Ed25519 keys, no support for confirm-on-use and incorrect implementation of the agent protocol causing protocol errors.
Platform-specific
Is Auto-Type supported on macOS and Windows?
Yes, Auto-Type works on all three supported platforms.
Does KeePassXC work on mobile phones? If not, which app would you recommend?
No, KeePassXC only works on desktop systems. Porting it properly to mobile platforms would require a full rewrite. You may be able to compile it for the mobile OS of your choice, but KeePassXC isn't at all optimized for mobile screen sizes and form factors, let alone multi-touch input. We also don't see any advantage in providing a mobile version of KeePassXC when there are excellent alternatives, already. For Android we recommend KeePass2Android and for iOS MiniKeePass or KeePass Touch.
Note: KeePass2Android does support YubiKeys via NFC, but its challenge-response implementation is incompatible with KeePassXC at the moment. We are working on a solution, though.
Why can't I copy advanced attributes to the clipboard or use certain shortcuts on KDE?
This is a “feature” in KDE's platform theme. It automatically adds ampersand (&) characters to on-screen text to allow you to trigger an action by pressing Alt+HOTKEY on your keyboard. Unfortunately, this “feature” causes more trouble than it does good. You can disable it by adding the following two lines to ~/.config/kdeglobals: 
[Development]
AutoCheckAccelerators=false
If you are like us and think this is a stupid feature, please consider voicing your concerns to the KDE guys.
Why do the tray menu and in-app shortcuts not work on Ubuntu/Unity?
This is a bug caused by appmenu-qt5.
You have 3 options:
  • Remove the appmenu-qt5 package
  • Set the environment variable UBUNTU_MENUPROXY=''
  • Set the environment variable QT_QPA_PLATFORMTHEME=''
Note: When you choose the first or third option, KeePassXC will lose the Unity look and feel.
Development
Why do I get an error when I try to build from source for this platform?
Please follow every step from our wiki page.