Issues
Can't save a password
- Is the folder initialized? Easiest way is to use the [Users] button and make sure you can encrypt for someone (e.g. yourself)
- Are you using Git? If not, make sure it is switched off.
I have an issue with GNOME keyring
- Disable GNOME keyring
- Create a
~/.gnupg/gpg-agent.confcontaining:
enable-ssh-support
write-env-file
use-standard-socket
default-cache-ttl 600
max-cache-ttl 7200
- See the pass FAQ for more troubleshooting tips.
I don't get a passphrase / PIN dialog
-
You'll need to install a pinentry package. On modern
distributions
pinentry-qt(Qt 6) is the usual choice;pinentry-qt5andpinentry-gtkare common fallbacks if your distro hasn't moved to Qt 6 yet. Search your package manager. You may also need to set the full path to that executable in your~/.gnupg/gpg-agent.conf, for example:pinentry-program /usr/bin/pinentry-qt -
On some systems it might be necessary to create a symbolic link
/usr/bin/pinentryto your pinentry application of choice eg:ln -s /usr/bin/pinentry-qt /usr/bin/pinentry -
On macOS
pinentry-program /usr/local/bin/pinentry-macworks after installingpinentry-macfrom Homebrew.
I have another issue with gpg
-
On modern systems,
gpgis usually GnuPG 2.x already. If your system has separategpgandgpg2keyrings (typically older or custom setups), your key may exist in one but not the other.
gpg --export [ID] > public.key
gpg --export-secret-key [ID] > private.key
gpg2 --import public.key
gpg2 --import private.key
rm public.key private.key
Where [ID] is your gpg key-id. If your setup is reversed, exchange
gpg and gpg2 accordingly.
Git doesn't work on Windows
Git for Windows comes with an ssh-askpass compatible
command, git-gui--askpass (located in
/mingw64/libexec/git-core/git-gui--askpass on PortableGit
version, presumably some place similar for the installed version).
To use it:
-
Set
SSH_ASKPASSenvironment variable to the full path ofgit-gui--askpass, for example:C:\Program Files\Git\mingw64\libexec\git-core\git-gui--askpass.exe -
Optionally set
GIT_ASKPASSto the same value so Git uses the same helper. -
Restart QtPass after setting the environment variables.
Example using PowerShell:
$env:SSH_ASKPASS = "C:\Program Files\Git\mingw64\libexec\git-core\git-gui--askpass.exe"
$env:GIT_ASKPASS = "C:\Program Files\Git\mingw64\libexec\git-core\git-gui--askpass.exe"
Or to make it permanent:
setx SSH_ASKPASS "C:\Program Files\Git\mingw64\libexec\git-core\git-gui--askpass.exe"
setx GIT_ASKPASS "C:\Program Files\Git\mingw64\libexec\git-core\git-gui--askpass.exe"
Note: After using setx, you'll need
to start QtPass in a new session (close and reopen your terminal, or
log out and back in) for the environment variables to take effect.
Git has issues with GPG SSH Authentication
This tutorial might resolve your issues. https://gitforwindows.org/OpenSSH-Integration-with-Pageant
gpg reports a missing /tmp/tst_integration-…/pubring.kbx
QtPass is pointing gpg at a GNUPGHOME that no longer
exists. The 1.7.0 test suite wrote its temporary keyring path into the
live configuration when make check was run as your own
user (for example by a distribution package build), and never removed
it. Delete the gpgHome= line from
~/.config/IJHack/QtPass.conf (or set it to empty) and
restart QtPass. Since 1.8.1 QtPass ignores a configured GPG home that
does not exist and shows a status message instead.
GPG says "Public key unusable" or "No secret key"
Your GPG key may not be trusted or has expired. Run
gpg --edit-key <KEYID> and:
-
Set the trust level to "ultimate" (
trustcommand) -
Check if the key has expired (
expirecommand to extend if needed) -
For smartcards/YubiKeys, ensure the card is connected and unlocked
(you can verify with
gpg --card-status)
What is the "Signing Key" in profile settings?
The Signing Key field in profile configuration is optional and usually should be left empty.
It is only needed if you want to create
detached signatures for your
.gpg-id files to verify the recipients list hasn't
been tampered with. Most users can ignore this field.
Common mistake: Putting your GPG key ID here will cause "Signature does not exist" errors when saving passwords. Leave it empty unless you specifically need signature verification.
How do I import someone else's GPG key?
Open the Users dialog (the Users button in the toolbar) and click Import key. You can:
- Pick an ASCII-armored
.ascfile from disk, or - Paste the armored key block from your clipboard.
Once imported, QtPass refreshes the user list and selects the new key
so you can tick it as a recipient. Binary keyrings aren't accepted
in this dialog; convert them first with
gpg --armor --export <KEYID>.
What does the Share submenu do?
Right-click on a folder in the password tree to access the Share submenu. It bundles the recipient-management actions in one place:
-
Re-encrypt all passwords: runs
pass initon the folder so its contents match the current.gpg-idrecipients. - Export my public key…: saves your public key as an ASCII-armored file you can hand to a teammate.
- Add recipient…: opens the user dialog scoped to this folder so you can toggle who can decrypt its passwords.
- What is this?: a short explainer dialog linking the three flows.
The submenu only appears on folders, not individual password files.
I removed someone, but they can still read some passwords
Saving recipients in the Users dialog changes the
recipient list (.gpg-id) of that folder and re-encrypts
the entries that use it. Some entries are not reached:
-
Folders below with a list of their own. For those, their own
.gpg-iddecides, not the one you saved. QtPass 1.8.4 and earlier gave every folder made with Add folder its own copy of the parent's list. To find every such list, run this with your own store path:find ~/.password-store -mindepth 2 -name .gpg-id- Without a signing key: delete a copy you do not need, then use Share › Re-encrypt all passwords on that folder.
- With a signing key: open Users for that folder, untick the person and save.
-
Hidden folders (names that start with a dot). QtPass does not show, search or re-encrypt them, as
pass lsdoes not list them (pass initdoes re-encrypt them). Move the entries into a normal folder, then re-encrypt. -
Copies elsewhere. Re-encrypting does not take back what the person could already read: Git history, backups and synced copies keep the old files. Change the passwords that matter.
How do I set up a one-time password (OTP/TOTP)?
QtPass generates TOTP codes itself (RFC 6238), so you no longer need
the pass-otp extension, and it works on every platform.
- Make sure Enable one-time password (OTP) support is checked on the Settings tab of the configuration dialog (it is on by default).
-
Store the account's
otpauth://URI in the entry. Put it in theOTPtemplate field, or on its own line in the body (the formpass otp insertwrites). A bare base32 secret works too. - Select the entry: QtPass shows a live code with a countdown and a copy button, refreshing automatically. SHA-1/SHA-256/SHA-512 and Steam Guard codes are all supported.
The shared secret itself is never shown on screen or copied; only the current code is.
QtPass shows an OTP code and I don't want it to
OTP support is enabled by default. To hide the live codes, uncheck
Enable one-time password (OTP) support on the
Settings tab of the configuration dialog. The choice
is remembered. Your entries are unchanged: the
otpauth:// secret stays in the file and QtPass simply
stops rendering a code for it.
OTP QR codes don't work on macOS
Applications launched from Finder don't inherit the shell PATH. Install QtPass via Homebrew (which sets up PATH correctly) or create a wrapper script that sets PATH before launching QtPass, for example:
#!/usr/bin/env bash
# Adjust PATH as needed for your Homebrew / QtPass installation
export PATH="/usr/local/bin:/opt/homebrew/bin:$PATH"
exec /Applications/QtPass.app/Contents/MacOS/qtpass "$@"
Save this script (e.g. as ~/bin/qtpass-wrapper.sh), make
it executable with chmod +x ~/bin/qtpass-wrapper.sh, and
configure your launcher (Automator app, custom .app bundle, or
shortcut) to run this script instead of starting QtPass directly.
QtPass doesn't follow my system language
QtPass uses the system language at startup. On some desktop environments, you may need to launch QtPass from the terminal or configure your desktop environment to pass the correct locale environment variables.
Where is the configuration stored?
QtPass tries to use the native configuration location for the operating system it is running on.
- Linux and BSD:
$HOME/.config/IJHack/QtPass.conf -
macOS:
$HOME/Library/Preferences/com.IJHack.QtPass.plist -
Windows registry:
HKEY_CURRENT_USER\Software\IJHack\QtPass
These settings can be overridden by a qtpass.ini file in
the folder where the application resides. So-called "portable
config".
There are some things to take care of when trying to sync on some systems (especially macOS, with regards to text and binary .plist files).
More information: https://doc.qt.io/qt-6/qsettings.html#platform-specific-notes
Where can I ask for help?
- Create an issue on GitHub.
- Send an email to help@qtpass.org
- Visit the Official QtPass site
Can I import from KeePass, LastPass or X?
- Yes, check passwordstore.org/#migration for more info.
Can I use my passwords on my phone or in my browser?
Yes: a pass store is a folder of GPG-encrypted files, so other apps can read the same one. They are separate projects; we list them with what to watch out for and do not vouch for them (checked October 2026).
-
Browser:
Browserpass
(Firefox, Chrome and Chromium on Linux, macOS and Windows) runs
gpgitself, so it works withoutpass. It matches sites by entry name, so name entries after the domain, such asgithub.com; one-time codes are off by default. PassFF (Firefox) needspassor gopass installed and reads one store. Both need their native helper and a graphical pinentry. -
Android:
Password Store
(agrahn's fork, on F-Droid) opens entries written by GnuPG 2.4
and newer, which the archived original app cannot. It needs a copy
of your secret key (no YubiKey), syncs only through a Git remote,
does not check signed
.gpg-idfiles, and cannot use post-quantum keys: one such recipient in a.gpg-idmakes that folder unreadable on the phone. - iPhone: Pass for iOS saves an edited entry encrypted to one key only, so keep shared stores read-only there. A YubiKey works with RSA keys only, and the app tries only the first recipient of an entry, so an entry encrypted to several keys may not open with it.
-
Command line:
gopass is
pass-compatible and runs
gpgdirectly; it does not check signed.gpg-idfiles.
QtPass itself on Android is an experiment for now.
I don't see icons on the buttons
You do not have the Qt SVG library installed. Please install using your favorite package manager.
I get icons that do not fit my (X11) default
- On some WindowManagers, Qt doesn't know what icon set to use. A trick:
export DESKTOP_SESSION=gnome
QtPass flashes dark at start, or ignores my light or dark theme
QtPass uses whatever theme your desktop gives Qt applications; it sets no colours of its own. Qt picks its platform theme plugin from the desktop session. KDE Plasma and LXQt bring their own, but on GTK desktops such as Cinnamon, MATE or Xfce Qt needs to be told, or it may start with its default colours and repaint once it reads your theme: a dark flash at start, or the wrong light or dark palette.
Set the platform theme in your session environment, for example in
~/.profile, then log out and in again:
export QT_QPA_PLATFORMTHEME=gtk3
On Gentoo you can also set it system-wide: put the line
QT_QPA_PLATFORMTHEME=gtk3 (without export)
in a file such as /etc/env.d/99qt-platformtheme, run
env-update, then log in again.
This needs Qt's GTK 3 platform theme plugin
(libqgtk3.so), which some distributions package
separately; others, such as Linux Mint, set a platform theme for you.
Instead of gtk3 you can use
xdgdesktopportal, or qt6ct once you have
installed and configured qt6ct (qt5ct with Qt 5).
The variable applies to every Qt application started from that session
(and, from /etc/env.d, to every user). To change it for
QtPass only, start it with
env QT_QPA_PLATFORMTHEME=gtk3 qtpass instead: copy
qtpass.desktop to
~/.local/share/applications and change its
Exec= line to that.
The AppImage bundles Qt's xdgdesktopportal theme but
not gtk3, and its start-up hook overwrites
QT_QPA_PLATFORMTHEME on GNOME and Xfce, so pass the theme
as an option instead:
./QtPass-*.AppImage -platformtheme xdgdesktopportal. That
theme reads your light or dark preference from the desktop's
settings portal, so it needs xdg-desktop-portal with a
backend for your desktop (such as xdg-desktop-portal-gtk,
or xdg-desktop-portal-xapp on Cinnamon, MATE and Xfce);
without one Qt keeps its default colours.
Whichever way you set it, quit QtPass completely first (it may still be running in the tray): starting it again only hands over to the running instance, which keeps the theme it started with.
QtPass does not set the variable itself, because that would override the platform integration of desktops that have their own. See #2126.
Can not find either qmake or qmake6
QtPass uses Qt6 by default. Use:
qmake6- for Qt6 (recommended, default)qmake- for Qt5
If you get an error like "QApplication" not found or Qt installation issues, make sure you're using the correct qmake version for your Qt installation.
On some systems, you may need to specify the full path, e.g.,
/usr/lib/qt6/bin/qmake6.
Qt installation issues
If you encounter Qt installation issues, you'll have to install the current version via your package manager or download it from https://www.qt.io/download/ and build from source.
I don't like the design, what gives?
- It's all on GitHub, clone, change and send a pull request.
- Open an issue and point out defects or better yet propose changes.
QtPass is not in my native language
- Unfortunately, QtPass might not support your native language, or the translations might be incomplete. Check if newer versions of QtPass support it.
- If translations are available but aren't working, try to set the language manually (see below) or open an issue.
How do I set the language manually?
QtPass uses the system language (via QLocale::system()).
Changing it depends on your platform:
-
Linux / BSD:
LANGUAGE=fr qtpasswill run QtPass in French.LC_ALLandLANGwork too; see the GNU gettext docs for the precedence order. -
macOS: environment variables like
LANGare not honored by Qt on macOS; Qt reads the CoreFoundation locale instead. Override per-app with:defaults write com.IJHack.QtPass AppleLanguages '(fr)'Or pass the override as a launch argument:
open -a QtPass --args -AppleLanguages '(fr)'Use
defaults delete com.IJHack.QtPass AppleLanguagesto revert. -
Windows: there is no environment-variable override; Qt reads the Windows display language via
GetUserDefaultLocaleName(). Change the system display language in Settings → Time & Language → Language, or add the desired language and move it to the top of your preferred-language list.
How can I help improve QtPass?
I would like to donate
-
Time:
- Read contributing documentation.
- Fork, clone, hack and send a pull request.
- Find an issue to work on.
- Participate in our bug bounty, you submit an issue and help us fix it, I send you a bounty.