KeePassXC

Resources

Home

Official documentation

Package information

User Guide

GitHub

Bugs (upstream)

keepassxc(1)

#keepassxc (webchat)

KeePassXC is a modern, secure, open-source, and cross-platform password manager. It is a fork of KeePassX that aims to incorporate stalled pull requests, features, and bug fixes that never made it into the main KeePassX repository.

Installation

USE Flags

USE flags for app-admin/keepassxc KeePassXC - KeePass Cross-platform Community Edition

+keyring	Enable support for use as the the system keyring
+network	Enable network support (e.g. for downloading favicons)
+ssh-agent	Use KeePassXC to unlock SSH keys
X	Add support for X11
autotype	Add support to autotype the passwords into other applications
browser	Enable communication with web browser plugins
doc	Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
keeshare	Enable KeeShare sharing integration
test	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
yubikey	Enable database unlocking via hardware keys supporting YubiKey-style HMAC-SHA1 protocol

Data provided by the Gentoo Package Database · Last update: 2025-04-20 20:17 More information about USE flags

Emerge

To install KeePassXC:

root #emerge --ask app-admin/keepassxc

Configuration

Files

KeepassXC configuration file containing basic user settings

• ~/.config/keepassxc/keepassxc.ini - Local (per user) configuration file.

Secret Service

KeePassXC also supports the Secret Service API, which allows client applications to securely store secrets in a service running in the user’s login session. To enable KeePassXC to handle the Secret Service API, following steps are required:

1. A new group or database must be created, either via the command-line interface or the graphical user interface. This group or database will be used for integration and can be accessed by applications via libsecret.
2. The newly created group or database must be exposed to other applications by selecting it in the Database Settings (Database --> Database Settings --> Secret Service Integration) and confirming the selection.
3. Now the Secret Service Integration in the settings must be activated, to allow applications to handle their secrets in the created group or database.

If it is not possible to activate the Secret Service Integration of KeePassXC because another Secret Service API is running (e.g. the gnome-secret service) the related secret service must be stopped and removed from auto-start. The desktop environment documentation (if any, otherwise the users environment) should be referred for guidance on how to do so. A general approach could be to remove the file /etc/xdg/autostart/gnome-keyring-secrets.desktop if the blocking service is gnome-keyring. Please make sure to make a backup of the file before removing it.

It is possible that the gnome-keyring secret service or another integration is starting before KeePassXC secret service. This can occur if an application requiring the Secret Service integration, starts before KeePassXC secret service API is running, resulting in KeePassXC's integration being blocked and the other service is loaded.

To resolve this, it is possible to simply remove the blocking application. For gnome-keyring for example:

root #emerge --ask --depclean --verbose gnome-base/gnome-keyring

Usage

user $keepassxc

Secret Service

Important
When using the secret service integration in KeePassXC, it is crucial to ensure that KeePassXC starts before other applications that require the integration, such as web browsers. To achieve this, the autostart option for KeePassXC can be enabled. Moreover, before using applications that need to store secrets, such as browsers, the related group or database for the secret service must be unlocked. Otherwise, if the applications start before an active secret service API is running, they will not be able to store secrets, and users will not stay logged in on websites between browser sessions.

Invocation

user $keepassxc --help

Usage: keepassxc [options] [filename(s)]
KeePassXC - cross-platform password manager

Options:
  -h, --help                   Displays help on commandline options.
  --help-all                   Displays help including Qt specific options.
  -v, --version                Displays version information.
  --config <config>            path to a custom config file
  --localconfig <localconfig>  path to a custom local config file
  --lock                       lock all open databases
  --keyfile <keyfile>          key file of the database
  --pw-stdin                   read password of the database from stdin
  --debug-info                 Displays debugging information.
  --allow-screencapture        allow screenshots and app recording
                               (Windows/macOS)

Arguments:
  filename(s)                  filenames of the password databases to open (*.kdbx)

Troubleshooting

KeePassXC cannot detect smart card

If KeePassXC cannot detect a hardware key/security key/smart card for Challenge-Response, install app-crypt/ccid; this package contains drivers for various smart cards.

root #emerge --ask app-crypt/ccid

After the package is installed, restart the pcscd service.

root #rc-service pcscd restart

Now try restarting KeePassXC then re-plugging the smart card; the smart card should be detected. If KeePassXC still cannot detect the smart card, additional steps might need to be taken depending on the manufacturer; a common step is the need to add udev rules for the card; to find the correct rules for the card, see the manufacturer's documentation.

Important
Installing the stand-alone CCID driver might prevent some applications from reading smart cards depending on certain USE flags.

For example, if app-crypt/gnupg (GPG) is installed with the smartcard USE flag, it will include the scdaemon service. If the usb USE flag is also enabled, scdaemon will have the additional functionality of being a smart card reader -- allowing GPG to read smart cards without any additional dependencies.

The issue is that if the stand-alone CCID driver, app-crypt/ccid, is installed, it will conflict with the built-in CCID driver for scdaemon -- preventing GPG from reading smart cards. But some packages (such as KeePassXC) require the stand-alone driver to use features provided by smart cards. There are two solutions to fix this, both of which make pcscd the smart card reader. After a solution has been chosen, see PCSC-Lite for additional configuration if needed.

• Solution 1:

Install GPG with the usb USE flag disabled then terminate the gpg-agent process then restart pcscd.

FILE /etc/portage/package.use/gnupg

app-crypt/gnupg -usb

root #emerge --ask -uND app-crypt/gnupg

root #killall gpg-agent

root #rc-service pcscd restart

• Solution 2:

Tell scdaemon to not use its built-in CCID driver -- this has the same affect if we run scdaemon with the --disable-ccid option; see man scdaemon.

FILE ~/.gnupg/scdaemon.conf

disable-ccid

Also ensure to terminate the gpg-agent process then restart pcscd.

root #killall gpg-agent

root #rc-service pcscd restart

Removal

Unmerge

KeePassXC can be removed with unmerging it:

root #emerge --ask --depclean --verbose app-admin/keepassxc

See also

• KeePassXC/cli — a command line interface for the KeePassXC password manager.
• Password management tools — This meta article is dedicated to secure password generation, auditing of generated passwords for security, and management of existing passwords.
• PCSC-Lite — implements the PC/SC international standard for PC to smartcard reader communication.

External resources

• Documenting KeePass KDBX4 file format
• Discussion on CVE-2023–35866
• What's the difference between KeePass / KeePassX / KeePassXC?