KeePassXC: User Guide

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. Except when otherwise stated in writing the copyright holders and/or other parties provide the program "as is" without Warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of Merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program Is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party Who modifies and/or conveys the program as permitted above, be liable to you for damages, including any general, Special, incidental or consequential damages arising out of the use or inability to use the program (including but not Limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of The program to operate with any other programs), even if such holder or other party has been advised of the possibility Of such damages.

The KeePassXC interface is designed for simplicity and easy access to your information. The main database view is split into four main partitions detailed below. You can open multiple databases at the same time, they will appear in tabs.

(A) Groups – Organize your entries into discrete groups to bring order to all of your sensitive information. Groups can be nested under each other to create a hierarchy. Settings from parent groups get applied to their children. You can hide this panel on the View menu.

(B) Tags – Dynamic groups of entries that can be quickly displayed with one click. Any number of custom tags can be added when editing an entry. This panel also includes useful pre-defined searches, such as finding expired and weak passwords.

(C) Entries – Entries contain all the information you want to store for a website or application you are storing in KeePassXC. This view shows all the entries in the selected group. Each column can be resized, reordered, and shown or hidden based on your preference. Right-click the header row to see all available options.

(D) Preview – Shows a preview of the selected group or entry. You can temporarily hide this preview using the close button on the right hand side or completely disabled in the application settings.

The toolbar provides a quick way to perform common tasks with your database. Some entries in the toolbar are dynamically disabled based on the information contained in the selected entry. Every common action in KeePassXC can be controlled with a keyboard shortcut as well.

(A) Database – Open Database, Save Database, Lock Database
(B) Entries – Create Entry, Edit Entry, Delete Selected Entries
(C) Entry Data – Copy Username, Copy Password, Copy URL, Perform Auto-Type
(D) Tools – Password Generator, Application Settings
(E) Search

Users can configure KeePassXC to their personal tastes with a wide variety of general and security settings that apply to the whole application. These settings are accessible from Tools → Settings or the cog wheel icon from the toolbar. Settings include: startup options, file management, entry management, user interface, language, security timeouts, and convenience.

By default, KeePassXC prevents recordings and screenshots of the application window on Windows and macOS. This prevents inadvertent spillage of information during meetings and disallows other applications to capture the window contents. If you would like to enable screen capture, you must start the application with the --allow-screencapture command line flag.

You can use the following command line options to tailor the application to your preferences:

Additionally, the following environment variables may be useful when running the application:

To start using KeePassXC, you need to first create a database that will store the password and other details.

To create a database, perform the following steps:

To open an existing database, perform the following steps:

On Windows and macOS, subject to hardware availability, your credentials can be securely stored to enable subsequent unlocking of your database through biometric authentication. This is enabled by default on Windows using Windows Hello and on macOS using Touch ID or Apple Watch services. You can disable this feature in the Application Settings under the Security section.

When your database is locked, you will see the following unlock dialog. Simply press Enter or click on Unlock Database to initiate the biometric authentication process. If you are using a hardware key (e.g. Yubikey), it must be connected to your computer to complete the unlock.

By default, KeePassXC will show entries that are expired or will be expiring within 3 days after unlocking the database. This feature allows you to change your passwords before they expire and be aware of passwords that are no longer valid. You can disable or change this feature in the Application Settings.

There are three ways that KeePassXC can handle database files. This behavior is set in the Application Settings under File Operations.

In addition to these save options, KeePassXC can create a backup of your existing database file just prior to saving. This backup will be saved at the path specified in the Backup destination field. This path can be absolute or relative. The latter will be resolved according to the databases path. It is possible to specify a custom naming scheme with placeholders. See Backup Path Placeholders for available placeholders and examples.

All the details such as usernames, passwords, URLs, attachments, notes, and so on are stored in database entries. You can create as many entries as you want in the database.

To add an entry, perform the following step:

To edit the details in an entry, perform the following steps:

Timed One-Time Passwords (TOTP) are a popular choice for two-factor authentication methods. These codes are typically six digits long and change every 30 seconds. They are derived from a shared secret value and the current time. Once set up, KeePassXC can calculate TOTP codes like any authenticator app, such as Google Authenticator. The codes can be used with copy/paste, browser extension, and Auto-Type.

To add TOTP to a database entry, you must first retrieve the secret string from the website or application you are authenticating to. Often this secret is accompanied with a QR code and can be copy/pasted below. Example:

Once obtained, right-click the desired entry (1), choose TOTP → Set up TOTP…​ (2), and the setup dialog will appear. In that dialog, paste the secret code from the website (3), setup any custom settings (rare) (4), then press OK to save the settings.

After an entry is configured with TOTP, you will see a clock icon in that entry’s row and have the ability to reveal the current code in the preview pane. Additionally, you can navigate to the entry’s TOTP menu to show the code in a separate window. You can also view the secret and configuration as a QR code for exporting to a mobile device. TOTP codes can be entered into forms with the browser extension, with Auto-Type by using the {TOTP} placeholder, or via menu options in the Auto-Type selection dialog.

To delete an entry, perform the following steps:

Creating a clone of an entry provides you a ready-to-use template for creating new entries with similar details of a master entry.

To create a clone of an existing entry, perform the following steps:

The following fields can be searched along with their abbreviated name in parentheses:

The following tables lists a few samples search queries for your reference:

A lot of applications and web sites now require providing additional information when you create accounts. The additional information is used to block hackers if any suspicious activity is detected. In addition, the additional information you provide can be used to reset passwords if you forget them. You can also store arbitrary information here that can be copied to the clipboard or Auto-Typed using the {S:<ATTR_NAME>} action code.

To protect an attribute from being displayed by default, activate the Protect checkbox (A). To show the contents of the attribute while keeping it protected, press the Reveal button (B).

You can attach files to any entry in your database by pressing the Add button (A). These files are added to the database and stored as encrypted binaries. You can open, save, or delete attachments from this interface (B).

You can change the foreground (A) and/or background (B) color that this entry will use in the entry lists. Click the corresponding box to open the color picker dialog.

You can select an icon to be displayed with each entry for easy identification. KeePassXC comes with a set of default icons that you can use or you can use your own custom icons. If you defined a URL with an entry, you can also download the favorite icon for that particular website.

KeePassXC lets you view the basic properties such as date and time of creation, modification, and when last accessed. This is also where you can retrieve an entry’s UUID for use in references.

KeePassXC maintains a history of changes you make to your entries. Each time you change an entry, KeePassXC automatically creates a backup copy of the current, non-modified entry before saving the new values. You can view the changes you made previously, restore, and delete the history of changes you made. The age of the history item, the changes that were made, and the entry’s size are shown in the table view.

It is advisable to have a backup replica YubiKey In case your main YubiKey gets damaged, lost, or stolen. The same HMAC key will need to be written to both keys. To do this you can either use the YubiKey Personalization Tool GUI or the ykpersonalize CLI tool. The steps for the CLI tool are shown:

You will be asked to enter the HMAC key you created earlier, copy/paste they key output in the first step. Repeat step 2 for your second YubiKey using the same HMAC key from before. We recommend storing your HMAC key in a safe place (e.g., printed on paper) in case you need to recreate another key.

Save your 1Password Vault locally to create an OPVault directory. Please see 1Password instructions on how to do this. Once an OPVault is created, perform the following steps:

KeePass 1 database is an older format of the database created using a legacy version of KeePass. KeePassXC lets your import this older format of the database and you can seamlessly start using this database in your new KeePassXC application.

To import a KeePass 1 database file in KeePassXC, perform the following steps:

To generate random passwords, specify the characters to be used in your choice of password (for example, upper-case letters, digits, special characters, and so on) and KeePassXC will randomly pick characters out of the set.

To generate the random password using Password Generator, perform the following steps:

A passphrase is a sequence of words or other text used to control access to your applications and data. A passphrase is specifically designed to be simple to remember but hard to guess. For this reason, we do not recommend making passphrases too complex; if you require something that is more complex than you could easily remember, it is better to use a randomly generated password instead.

You can download the KeePassXC-Browser extension from your web browser. To download the KeePassXC-Browser extension, perform the following steps:

To start using KeePassXC-Browser, you must configure it so that it can communicate with the KeePassXC application on your desktop.

To configure KeePassXC-Browser, perform the following steps:

The KeePassXC-Browser extension lets you automatically populate the entries from your KeePassXC database into the fields on websites you visit. To do so, perform the following steps:

You can see a cross-section of all browser-related settings applied to entries within a database through the Browser Statistics report. To access these, use the Database → Database reports…​ menu option then click on Browser Statistics on the left-hand menu. From here you can see all entries with URLs applied to them, explicitly allowed and denied URLs, and any entries with custom browser settings.

You can configure unique browser integration behavior for each entry. This allows you to add multiple URLs to an entry, hide an entry from the browser integration, and more. To access these settings, open an entry for editing then click on Browser Integration option in the left-hand menu (1).

After opening the settings you can add any number of additional URLs by clicking the Add button (2) and typing the URL in the list to the left (3).

To set options for all entries within a group, edit the group and go to the browser integration section (1). Here you can explicitly disable access to all entries under a group hierarchy to the browser extension. You can set other useful options for groups of entries as well.

Database-wide operations are available in the database settings. To access these use the Database → Database settings…​ menu option. Click on Browser Integration on the left-hand menu. From here you can disconnect all browsers, convert legacy KeePass-HTTP settings, reset all entry-level settings, and refresh the database root group ID (useful when making copies of your database file).

Finally, advanced application-wide settings are available in the Browser Integration tab of the application settings.

KeePassXC supports Passkeys directly through the Browser Integration service. Passkeys are only supported with the use of the KeePassXC Browser Extension and a properly connected database. To enable Passkey support on the extension, you must check the Enable Passkeys option in the extension settings page.

Optionally, you can disable falling back to the built-in Passkey support from your browser and operating system. If left enabled, the extension will show the default Passkey dialogs if KeePassXC cannot handle the request or the request is canceled.

Creating a new Passkey and authenticating with it is a simple process. This workflow will be demonstrated using GitHub as an example site. Please note that GitHub allows two use cases for Passkeys, one for 2FA only and the other for replacement of username and password entirely. We will be configuring the latter use case in this example.

After navigating to GitHub’s Settings → Password and authentication, there is a separate section shown for Passkeys.

After clicking the Add a Passkey button, the user is redirected to another page showing the actual configuration option.

Clicking the Add Passkey button now shows the following popup dialog for the user, asking confirmation for creating a new Passkey.

After the Passkey has been registered, a new entry is created to the database under KeePassXC-Browser Passwords with (Passkey) added to the entry title. The entry holds additional attributes that are used for authenticating the Passkey.

After registration, GitHub will ask a name for the Passkey. This is only relevant for the server.

Now the Passkey should be shown on the GitHub’s Passkey section.

The Passkey created in the previous section can now be used to login to GitHub. Instead of logging in with normal credentials, choose Sign in with a passkey at the bottom of GitHub’s login page.

After clicking the button, KeePassXC-Browser detects the Passkeys authentication and KeePassXC shows the following dialog for confirmation.

After confirmation user is now authenticated and logged into GitHub.

You can define a global Auto-Type hotkey that starts the Auto-Type process. To configure the hotkey, perform the following steps:

Navigate to Tools → Settings → Auto-Type tab (1). Click into the Global Auto-Type shortcut box and press the desired key combination that will trigger the Auto-Type process (2).

You can configure additional Auto-Type settings in this window such as start delay, inter-key typing delay, and matching options. If Auto-Type is not working well for you, try adjusting the default delays.

You can also set the time to remember the last used entry between presses of the global Auto-Type hotkey. This is useful for typing parts of a sequence during complex login workflows without having to find the specific each time.

Each entry in your database can have multiple Auto-Type sequences associated with various window titles. Simulated key presses can be sent to any other currently open window of your choice (web browser windows, login dialogs boxes, and so on). When the Global Auto-Type hotkey is pressed, KeePassXC will search your database for entries matching the current selected window title.

To configure Auto-Type sequences for your entries, perform the following steps:

The global Auto-Type keyboard shortcut is used when you have focus on the window you want to type into. To make use of this feature, you must have previously configured an Auto-Type hotkey.

When you press the global Auto-Type hotkey, KeePassXC searches all unlocked databases for entries that match the focused window title. The Auto-Type selection dialog will appear in the following circumstances: there are no matches found, there are multiple matches found, or the setting "Always ask before performing Auto-Type" is enabled. The selection is remembered for a short while to help retype with the same entry in quick succession.

Perform the selected Auto-Type sequence by double clicking the desired row or pressing Enter. Press the up and down arrows to navigate the list. Sequences can be filtered through the text edit field.

Search the unlocked databases by activating Search Database radio button. Use the text edit field to issue search queries using the same syntax as database searching.

The option to type just the username, password, or current TOTP value is available by right-clicking the desired row or expanding the Type Sequence button options. You can also copy these values to the clipboard.

You can quickly activate the default Auto-Type sequence for a particular entry using Entry-Level Auto-Type. For this operation, the KeePassXC window will be minimized and the Auto-Type sequence occurs in the previously selected window. You can perform Entry-Level Auto-Type from the toolbar icon (A), entry context menu (B), or by pressing Ctrl+Shift+V.

To use sharing, you need to enable it for the application.

If you checked Allow export in the Sharing settings you can now share a group of passwords. Sharing is always defined on a particular group. If you enable sharing on a group, every entry under this group, and its children, are shared. If you enable sharing on the root node, every password inside your database gets shared!

The export file will not be generated automatically. Instead, each time the database is saved, the file gets written. The file should be written to a location that is accessible by others. An easy setup is a network share or storing the file in cloud storage.

KeeShare watches the container for changes and merges them into your database when necessary (Import and Synchronize modes). Entries merge in time order; older data is moved to the history of the entry.

A shared group shows a cloud icon badge over the group icon (A) and a banner is displayed showing the sharing mode and file location (B). If the share is disabled or unavailable, the cloud icon will show as red with a white X.

Sharing relies on the combination of file exports and imports as well as the synchronization mechanism provided by KeePassXC. Since the merge algorithm uses the history of entries to prevent data loss, this history must be enabled and have a sufficient size. Furthermore, the merge algorithm is location independent, therefore it does not matter if entries are moved outside of an import group. These entries will be updated nonetheless. Moving entries outside of export groups will prevent a further export of the entry, but it will not ensure that the already shared data will be removed from any client.

KeeShare uses a custom certification mechanism to ensure that the source of the data is the expected one. This ensures that the data was exported by the signer but it is not possible to detect if someone replaced the data with an older version from a valid signer. To prevent this, the container could be placed at a location which is only writeable for valid signers.

If you are using a modern desktop Linux distribution it is very likely the OpenSSH agent is already configured and running when you have logged in to a graphical desktop session. This should be true for distributions like Debian, Ubuntu (including Kubuntu, Xubuntu and Lubuntu), Linux Mint, Fedora, ElementaryOS and Manjaro.

First, open a terminal and check the output of ssh-add -l:

If you either got a list of fingerprints or the message above the agent is already running and no further setup is required. If instead you got a message saying "Could not open a connection to your authentication agent." that means the agent is either misconfigured or not running at all.

Since every distribution and desktop environment is configured differently there is no general guide how to properly set it up yourself. The general rule of thumb, however, is that ssh-agent needs to be started as part of the startup programs for a session in a way its environment variables are exposed to all processes started by the desktop environment. One of the easiest ways to achieve this is to enable GNOME Keyring which should in turn start the agent as part of its services.

There are many guides on the internet how to hack your login shell to start an agent but it is very prone to errors and is not a supported configuration. If you prefer the login shell startup hack you need to set it up with a static socket path and use the SSH_AUTH_SOCK override option in SSH Agent settings to match that.

Apple has made OpenSSH an integrated part of macOS with automatic agent startup when it is first used. No further configuration is needed.

The SSH Agent integration on Windows supports both PuTTY Pageant and OpenSSH for Windows 10. Since Pageant is currently still the most widely used implementation and is easily installable on any version of Windows, it is the default on KeePassXC. However, Microsoft includes a native OpenSSH client implementation with Windows 10 since autumn 2018 that can be used instead. If you would like to self-manage your OpenSSH version you can use the builds offered via their official GitHub repository.

By default the SSH Agent integration plugin is disabled. To enable integration, follow the steps below to access the settings:

On the settings page you can enable the integration by checking Enable SSH Agent integration. When the integration is enabled coming back to the settings page also shows if connection to the agent is working.

On Windows, you have the option to select Pageant and/or OpenSSH for Windows. On macOS and Linux, the system ssh-agent will be used automatically and the settings page shows the current value of SSH_AUTH_SOCK environment variable which is used to connect to the running agent and an option to manually override the automatically detected path.

If the value of SSH_AUTH_SOCK is empty it means the agent is not properly configured and KeePassXC will be unable to connect to it unless you provide a static override path to the socket.

KeePassXC only supports keys in the OpenSSH format. On Windows, PuTTYgen saves keys in its own format by default and you will need to convert them to OpenSSH format before being used. In this guide we are going to generate a standard RSA key in the default size.

The last step is to setup an entry to contain the SSH Agent settings and key file you generated.

If you chose to not autoload the key on database unlock, you can manually make the key available by using the context menu from the entry list.

A reference to another entry’s field is possible using the shorthand syntax: {REF:<FIELD>@<SEARCH_IN>:<SEARCH_TEXT>}

<FIELD> and <SEARCH_IN> can be one of following:

Examples:
{REF:U@I:033054D445C648C59092CC1D661B1B71}
{REF:P@T:Other Entry}
{REF:A@O:Attribute 1}

Text Conversions:

{T-CONV:/<PLACEHOLDER>/<METHOD>/}
Convert resolved placeholder (e.g., {USERNAME}, {PASSWORD}, etc.) using the following methods: UPPER, LOWER, BASE64, HEX, URI, URI-DEC.

{T-REPLACE-RX:/<PLACEHOLDER>/<SEARCH>/<REPLACE>/}
Use regular expressions to find and replace data from a resolved placeholder. Refer to match groups using $1, $2, etc.