gopass needs some external programs to work:
It is recommended to have either rng-tools
or haveged
installed to speed up
key generation if these are available for your platform.
apt-get update
apt-get install git gnupg rng-tools
yum install gnupg2 git rng-tools
pacman -S gnupg2 git rng-tools
If you haven't already, install homebrew. And then:
brew install gnupg2 git
- Download and install GPG4Win.
- Download and install the Windows git installer.
Alternatively, these can be installed via chocolatey,
choco install git
choco install gpg4win
scoop install git
# add Extras bucket, if you haven't already
# scoop bucket add extras
scoop install gpg4win
or winget.
winget install Git.Git
winget install GnuPG.Gpg4win
For OpenBSD -current:
pkg_add gopass
For OpenBSD 6.2 and earlier, install via go install
.
Please note that the OpenBSD builds uses pledge(2)
to disable some syscalls,
so some features (e.g. version checks, auto-update) are unavailable.
For FreeBSD 11 and newer:
pkg install gopass
gopass depends on the gpg
program for encryption and decryption. You must have a
suitable key pair. To list your current keys, you can do:
gpg --list-secret-keys
If there is no output, then you don't have any keys. To create a new key:
gpg --full-generate-key
You will be presented with several options:
- Key type: Choose either "RSA and RSA" or "DSA and ElGamal".
- Key size: Choose at least 2048.
- Validity: 5 to 10 years is a good default.
- Enter your real name and primary email address.
- A comment is not necessary.
- Pass phrase: Make sure to pick a very long pass phrase, not just a simple password. Remember this should be stronger than any of the secrets you store in the password store. You can configure the GPG Agent later to save you repetitive typing.
Now, you have created a public and private key pair. If you don't know what that means, or if you are not familiar with GPG, we highly recommend you do a little reading on the subject. Check out the following manuals:
Depending on your operating system, you can either use a package manager, download a pre-built binary, or install from source. If you have a working Go development environment, we recommend building from source.
If you haven't already, install homebrew. And then:
brew install gopass
Alternatively, you can install gopass from the appropriate Darwin release from the repository releases page.
If you're using a password on your GPG key, you also have to install pinentry-mac
from brew and configure it in your ~/gpg/gpg-agent.conf
:
brew install pinentry-mac
PINENTRY=$(which pinentry-mac)
echo "pinentry-program ${PINENTRY}" >>~/.gnupg/gpg-agent.conf
defaults write org.gpgtools.common UseKeychain NO
The last step is important if you want to stop pinentry-mac
from caching your passphrase in the MacOS Keychain by default (indefinitely).
WARNING: The official Debian repositories (and derived distributions) contain
a package named gopass
that is not related to this project in any way.
It's a similar tool with a completely independent implementation and feature set.
We are aware of this issue but can not do anything about it.
When installing on Ubuntu or Debian you can either download the deb
package,
install manually or build from source or use our APT repository.
$ curl https://packages.gopass.pw/repos/gopass/gopass-archive-keyring.gpg | sudo tee /usr/share/keyrings/gopass-archive-keyring.gpg >/dev/null
$ cat << EOF | sudo tee /etc/apt/sources.list.d/gopass.sources
Types: deb
URIs: https://packages.gopass.pw/repos/gopass
Suites: stable
Architectures: all amd64 arm64 armhf
Components: main
Signed-By: /usr/share/keyrings/gopass-archive-keyring.gpg
EOF
$ sudo apt update
$ sudo apt install gopass gopass-archive-keyring
Note: We also have an unstable track that sometimes contains pre-release versions. Use https://packages.gopass.pw/repos/gopass-unstable
if you want to help with early testing.
First, find the latest .deb release from the repository releases page. Then, download and install it:
wget [the URL of the latest .deb release]
sudo dpkg -i gopass-1.2.0-linux-amd64.deb
There is an overlay that includes gopass. Run these commands to install gopass through emerge
.
layman -a go-overlay
emerge -av gopass
dnf install gopass
There is an unofficial RPM build maintained by a contributor.
# if you're using dnf (needs dnf-plugins-core)
dnf copr enable daftaupe/gopass
dnf install gopass
# of if you're using an older distribution (needs yum-plugin-copr)
yum copr enable daftaupe/gopass
yum install gopass
pacman -S gopass
You can install gopass
with Chocolatey,
choco install gopass
scoop install gopass
or winget.
winget install gopass.gopass
Alternatively, download and install a suitable Windows build from the repository releases page.
If you have Go already installed, you can use go install
to automatically download the latest version:
GO111MODULE=on go install -u github.com/gopasspw/gopass@latest
WARNING: latest
is not a stable release. It is recommended to use a specific version.
If $GOPATH/bin
is in your $PATH
, you can now run gopass
from anywhere on your system.
To use the self-updater run:
gopass update
or to upgrade with Go installed, run:
go install github.com/gopasspw/gopass@latest
Various editors may store temporary files outside of the secure working directory when editing secrets. We advise you to check and disable this behavior for your editor of choice.
Here are a few useuful example settings:
" neovim on Linux
autocmd BufNewFile,BufRead /dev/shm/gopass* setlocal noswapfile nobackup noundofile shada=""
" neovim on MacOS
autocmd BufNewFile,BufRead /private/**/gopass** setlocal noswapfile nobackup noundofile shada=""
" vim on Linux
autocmd BufNewFile,BufRead /dev/shm/gopass* setlocal noswapfile nobackup noundofile viminfo=""
" vim on MacOS
autocmd BufNewFile,BufRead /private/**/gopass** setlocal noswapfile nobackup noundofile viminfo=""
Note: gopass will attempt to detect the correct hardning flags to be used for the editor. It will pass them on invocation.
If you are migrating from pass to gopass, you can simply use your existing password store and everything should just work. Furthermore, it may be helpful to link the gopass binary so that you can use it as a drop-in replacement. For example, assuming $HOME/bin/
exists and is present in your $PATH
:
ln -s $GOPATH/bin/gopass $HOME/bin/pass
Before migrating to gopass, you may have been using other password managers (such as KeePass, for example). If you were, you might want to import all of your existing passwords over. Because gopass is fully backwards compatible with pass, you can use any of the existing migration tools found under the "Migrating to pass" section of the official pass website, for example pass-import.
If you use Bash, you can use the following command to enable auto completion for all users for sub-commands like gopass show
, gopass ls
and others.
gopass completion bash | sudo tee $(pkg-config --variable=completionsdir bash-completion)/gopass
To enable bash completions for the current user only:
grep -q "source <(gopass completion bash)" ~/.bashrc || echo "source <(gopass completion bash)" >> ~/.bashrc
MacOS: The version of bash shipped with MacOS may require a workaround to enable auto completion. If the instructions above do not work try the following one:
source /dev/stdin <<<"$(gopass completion bash)"
If you use zsh, make install
or make install-completion
should install the completion in the correct location.
If zsh autocompletion is still not functional, or if you want to install it manually, you can run the following commands:
gopass completion zsh > ~/_gopass
sudo mv ~/_gopass /usr/share/zsh/site-functions/_gopass
rm -i ${ZDOTDIR:-${HOME:?No ZDOTDIR or HOME}}/.zcompdump && compinit
Then exit and re-run zsh if the last command failed.
Notice that it is important to directly redirect Gopass' output to a file,
using pipes or echo mess up the output. Also notice that the generated _gopass
file is
a completion file that is supposed to be handled by zsh and to be installed in the zsh
completions directory, as defined by either the standard /usr/share/zsh/site-functions/
path,
or by a user-specified fpath
folder. It is not meant to used with source
.
If zsh completion is still not working, you might want to add the following to your .zshrc
file:
autoload -U compinit && compinit
if you don't have it already.
If you use the fish shell, you can enable experimental shell completion by the following command:
mkdir -p ~/.config/fish/completions and; gopass completion fish > ~/.config/fish/completions/gopass.fish
and start a new shell afterwards.
Since writing fish completion scripts is not yet supported by the CLI library we use, this completion script is missing a few features. Feel free to contribute if you want to improve it.
In earlier versions gopass supported dmenu. We removed this and encourage you to call dmenu yourself now.
This also makes it easier to call gopass with any drop-in replacement of dmenu, like rofi, for example, since you would just need to replace the dmenu
call below by rofi -dmenu
.
# Simply copy the selected password to the clipboard
gopass ls --flat | dmenu | xargs --no-run-if-empty gopass show -c
# First pipe the selected name to gopass, decrypt it and type the password with xdotool.
gopass ls --flat | dmenu | xargs --no-run-if-empty gopass show -o | xdotool type --clearmodifiers --file -
# First pipe the selected name to gopass, and type the value from the key "username" with xdotool.
gopass ls --flat | dmenu | xargs --no-run-if-empty -- bash -c 'gopass show -f $0 username' | head -n 1 | xdotool type --clearmodifiers --file -
# Oterwise type the name of the entry using xdotool, in case you are not including a username key in your entries
gopass ls --flat | dmenu | sed 's!.*/!!' | tr -d '\n' | xdotool type --clearmodifiers --file -
You can then bind these command lines to your preferred shortcuts in your window manager settings, typically under System Settings > Keyboard > Shortcuts > Custom Shortcuts
. In some cases you may need to wrap it with bash -c 'your command'
in order for it to work (tested and working in Ubuntu 18.04).
Gopass allows filling in passwords in browsers leveraging a browser plugin like gopass bridge. The browser plugin communicates with gopass-jsonapi via JSON messages. To allow the plugin to start gopass-jsonapi, a native messaging manifest must be installed for each browser. Chrome, Chromium and Firefox are supported, currently.
Upgrade to gopass v1.10 / v1.11:
gopass-jsonapi
is now its own binary file, which you need to install separately.
The binary for v1.10 and v1.11 can be downloaded and unpacked from archive files on Github Releases.
You need to run gopass-jsonapi configure
after the upgrade to configure your browser for the new command.
Upgrade to gopass v1.12 The new binary can be downloaded from the latest Github Release on gopass-jsonapi.
For more detailed instructions, please read: gopass-jsonapi/README.
This is the recommended way to use gopass
.
NOTE: We do recommend to use a private Git repository. A public one will keep your credentials secure but it will leak metadata.
To use gopass
with git
either create a new git repository or clone an existing
password store.
Create a new repository, either locally or on a server, then specify this
repository during the gopass setup
.
$ gopass setup --crypto gpg --storage gitfs # used by default
[...]
# provide an existing, empty git remote, e.g. git@gitlab.example.org:john/passwords.git
If you have created a password store with git
, gopass
can easily clone it.
gopass clone git@gitlab.example.org:john/passwords.git
The recommended way to use Gopass is to sync your store with a git repository, preferably a private one, since the name and path of your secrets might reveal information that you'd prefer to keep private.
However, shall you prefer to, you might also use the noop
storage backend that is meant to store data on a cloud provider instead of a git server.
Please be warned that using cloud-based storage may negatively impact the confidentiality of your store. However, if you wish to use one of these services, you can do so.
For example, to use gopass with Google Drive:
gopass setup --storage fs
mv .password-store/ "Google Drive/Password-Store"
gopass config mounts.path "~/Google Drive/Password-Store"
Because gopass is fully backwards compatible with pass, you can use some existing graphical user interfaces / frontends:
- Android - PwdStore
- iOS - Pass for iOS
- Windows / MacOS / Linux - QtPass
There is also Gopass UI which was exclusively implemented for gopass and is available for MacOS, Linux and Windows.
Others can be found at the "Compatible Clients" section of the official pass website.
Once you have installed gopass, check out the features documentation for some quick usage examples.
Running gopass
with no existing store will start the onboarding wizard which
will guide you through the setup of gopass.
In order to simplify the setup of gopass for your team members it can be run in a fully scripted bootstrap mode.
# First initialize a new shared store and push it to an empty remote
gopass --yes setup --remote github.com/example/pass.git --alias example --create --name "John Doe" --email "john.doe@example.com"
# For every other team member initialize a new store and clone the existing remote
gopass --yes setup --remote github.com/example/pass.git --alias example --name "Jane Doe" --email "jane.doe@example.com"
The first command will create a new mount named example
and push it to an empty (--create
) remote.
It will fail if the remote at github.com/example/pass.git
is not empty.
The second command will clone the existing (no --create
flag) remote github.com/example/pass.git
and mount it as the mount point example
.