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) Searches and 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 and custom saved searches, such as finding expired and weak passwords.

(C) Entries – Entries contain all the information 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 interact with most information stored in an entry from here without opening the entry for editing. You can temporarily hide this preview using the down-arrow button on the right hand side or completely disable it from the View menu.

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 – Database Settings, Reports, Password Generator, Application Settings
(E) Search

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 temporarily, navigate to View menu and select Allow Screen Capture. Alternatively, you can start the application with the --allow-screencapture command line flag.

You can customize the appearance of KeePassXC to your liking. The following options are available in the View menu:

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 controls, and integration settings (Auto-Type, Browser, etc).

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:

The following options can be set when running the Windows Installer MSI in an unattended installation:

Example: msiexec.exe /q /i KeePassXC-Y.Y.Y-WinZZ.msi AUTOSTARTPROGRAM=0

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:

The database file that you create might contain highly sensitive data and must be stored in a very secure way. You must make sure that the database is always protected with a strong and long password. The database file that is protected with a strong and long password is secure and encrypted while stored on your computer or cloud storage service.

Make sure that you or someone else does not accidentally delete the database file. Deletion of the database file will result in the total loss of all your information (including all your passwords!) and a lot of inconvenience to manually retrieve your logins for various web applications. Do not share the credentials to access your database file with anyone unless you absolutely trust them (spouse, child, etc.).

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.

Entries in KeePassXC are the fundamental units where all your sensitive information is stored. Each entry can contain various fields such as usernames, passwords, URLs, attachments, and notes. You can create, edit, clone, and delete entries as needed. Additionally, KeePassXC supports advanced features like TOTP for two-factor authentication, custom attributes, and entry history to track changes over time. Proper management of entries ensures that your data is organized, secure, and easily accessible when needed.

KeePassXC offers several advanced options for managing your database entries. Additional Attributes allow you to store extra information required by some applications and websites. Attachments enable you to attach files to entries, stored as encrypted binaries, which can be previewed directly in the application (text and images). Icons can be selected or downloaded for easy identification of entries. The Properties section lets you view basic properties such as creation, modification, and last accessed times, and retrieve an entry’s UUID for references. KeePassXC also maintains a history of changes to entries, allowing you to view, restore, or delete previous versions of an entry.

KeePassXC provides a robust search that enables you to find specific entries in the databases using different modifiers, wild card characters, and logical operators. By default, search considers the following fields when matching your query: Title, Username, URL, Tags, and Notes. To include other fields and/or narrow your search to specific fields, you can use the search syntax described below.

KeePassXC allows you to merge entries from one database into another through the Database → Merge From Database menu item. When merging, entries from the specified database will be imported into your currently open database. The merge process compares entries based on their unique identifiers (UUIDs) and modified timestamp. When an entry UUID matches, no matter which group it is in, the most recently modified version will be made the current and the previous version will be placed into the entry’s history. Any new entries and/or groups will be added to the open database. This feature is useful for consolidating multiple databases or synchronizing databases from conflict files in a cloud storage system.

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.

Alternatively, backups can be created on-demand using the Database → Save Database Backup…​ menu feature.

You can setup one or more databases to open automatically when you unlock a single database. This is done by (1) defining a special group named AutoOpen with (2) entries that contain the file path and credentials for each database that should be opened. There is no limit to the number of databases that can be opened.

To setup an entry for auto open perform the following steps:

KeePassXC offers some maintenance features that can be applied to clean up your database. Navigate to Database → Database settings then click on Maintenance on the left hand panel. The following screen appears. On this screen you can delete multiple icons at once and purge any unused icons in your database.

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.

KeePassXC allows you to import databases from various applications including 1Password (1PUX and OPVault), Bitwarden, and Proton Pass. Each import option involves selecting the file, providing necessary credentials (if required), and choosing to import into a new or existing database. Note that CSV, 1Password Export, Bitwarden, and Proton Pass files are unencrypted and should be securely deleted after import.

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 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.

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:

The KeePassXC-Browser Extension also lets you generate passwords directly in your browser. This feature can be used for websites with existing credentials as well as for new websites. You can then choose to update/add the credentials to your KeePassXC database directly from the Browser.

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).

Additional URLs also supports wildcards (with KeePassXC 2.7.10 and later). You can use URLs like:

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.

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.

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.