How to Use gopass: The Beginner's Guide (First GPG Key, First Store, the Git Lesson, and Team Sharing)

CodexFuse Team · 2026-11-07T01:57:41.400Z · 21 min read min read

How to Use gopass?

Gopass is a command-line password manager that stores every secret as one GPG-encrypted file inside a directory tree, and it versions that tree with git. Learning how to use gopass takes seven moves: install it from an official source, create a GPG key, run the setup wizard, add your first secrets, learn the daily show and generate commands, connect the store to git, and invite your team with recipients. This gopass tutorial follows the official README and the v1.17.4 man page, with every fact checked as of November 2026.

Git is the backbone of the whole design, because every password change becomes a commit you can review and revert. The Git beginner guide on CodexFuse covers the version-control habits this guide assumes, and the git lesson later in this guide builds directly on it.

This guide opens the cli-password lane in the dev-tools password-management cluster, and the base pillar is the VPS hosting guide on CodexFuse, which covers the Linux server where a team can host its own private password-store remote.

1. Install gopass from the official source for your operating system.
2. Create a GPG key, or choose the age backend instead.
3. Run gopass setup and pick your key.
4. Add your first secret with gopass insert or gopass generate.
5. Learn gopass ls, gopass show, and gopass find for daily use.
6. Connect the store to a private git remote and run gopass sync.
7. Add teammates as recipients so the store re-encrypts for them.

What Is gopass?

What is gopass, in one sentence? Gopass is the slightly more awesome standard Unix password manager for teams, in the project's own words. It is a command-line password manager written in Go, a drop-in replacement for pass, and as a cli password manager it suits developers and teams who already live in a terminal, keeping every secret in plain files you can see, back up, and version.

The project is old enough to trust and young enough to stay active. It was created on 2 February 2017, so it is 3,565 days old, or 9.8 years, as of this guide, and the last code push landed 2 days ago, on 5 November 2026. It holds 7,316 GitHub stars and 569 forks, with 87 open issues, under the MIT license, and it has shipped 106 releases at about 10.9 per year.

If you prefer a graphical vault, the Bitwarden beginner guide on CodexFuse covers the GUI lane, and the KeePassXC beginner guide covers the offline desktop vault. Gopass is the terminal lane: the same job, no window, everything in the shell, and the git history is the feature that sets it apart.

CodexFuse offers no gopass tool, so this guide teaches the open-source tool itself. Everything below starts from its public repository at github.com/gopasspw/gopass, and the repository name matters, because an unrelated Go module also carries the gopass name. There is no official mobile app, so the store lives on the machines where you install the tool.

How Do You Install gopass?

A gopass install starts with the official source for your operating system, never with a random package search. The project publishes the same binary for Linux, macOS, Windows, FreeBSD, and OpenBSD, and most users also need GPG and git installed first. Check the releases page before you install, so you know the current version is v1.17.4, published 28 days ago on 10 October 2026.

Debian and Ubuntu users must read this part twice. Do not install the gopass package from the official Debian or Ubuntu repositories, because it is a completely different project that shares no code with gopass.pw. The official README warns about this in bold, and Debian removed its own gopass package from unstable in June 2025 after its author asked for removal, but the package still sits in older stable releases, so the trap is live on older systems.

On Debian and Ubuntu, use the official APT repo instead. Download the keyring to the system keyrings folder, add a sources file that points at packages.gopass.pw, then update and install gopass from that repo. The two commands below are the shape of it, and the full sources file follows them.

sudo curl -o /usr/share/keyrings/gopass-archive-keyring.gpg https://packages.gopass.pw/repos/gopass/gopass-archive-keyring.gpg
sudo apt update
sudo apt install gopass gopass-archive-keyring

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

Every other platform has a one-line route. Homebrew covers macOS and Linux, MacPorts covers macOS, and Windows has WinGet, Chocolatey, and Scoop, each with its own GPG prerequisite. The table below lists the official routes, and gopass update keeps the tool itself current once it is installed.

Fedora users may need the community copr repository first, and the README warns that installing from source at latest is not a stable release, so prefer a released version. Run gopass version after installing to confirm the binary answers, then run gopass doctor to check the binary dependencies, the git setup, and the store permissions before you create anything.

How Do You Create Your First GPG Key?

GPG is the lock on every secret, so the key comes before the store. Gopass can run with no dependencies at all, but most users need GPG and git, and an external editor is required for gopass edit. A GPG key and git are prerequisites, so this section is not optional, and the age backend near the end is the only way around it.

List your existing keys first, and create one only if the list is empty. The two commands below do both jobs, and the creation wizard asks for the key type, size, validity, name, and email in turn.

gpg --list-secret-keys
gpg --full-generate-key

Pick RSA and RSA for the key type, with a size of at least 2048 bits, and a validity of 5 to 10 years as a good default. Use your real name and primary email, and choose a very long passphrase, because it protects every secret in the store, and gpg-agent can cache it later so you do not type it for every command.

On macOS, a passphrase-protected key needs pinentry-mac installed and set in the GnuPG agent configuration, or the prompt will not appear correctly. If you have no GPG key and want the simpler road, the age backend section near the end shows the alternative, which needs no keyring at all.

How Do You Set Up Your First Store?

A gopass setup run is the current first command, and it opens an interactive wizard. It asks you to pick a private GPG key for encrypting secrets, then asks whether to add a git remote for the shared store. The wizard prints a welcome banner, configures the store, and leaves you with a working vault in under a minute.

By default, gopass setup uses GPG encryption and git storage. It creates the new password store in the local share folder under gopass stores root, and it writes the configuration under the gopass config folder. Those paths are the defaults, and the wizard asks before it changes anything.

The older gopass init command still exists in v1.17.4, and the official docs and homepage still show it in places, so older guides are not lying. Setup is the documented entry point in the current README and man page, so this guide teaches setup and mentions init only here, and you should never trust a guide that claims init was deleted.

If a store already exists, clone it instead of setting one up. The command below clones a remote store onto your machine, and running bare gopass with no store at all starts the same onboarding wizard. The setup command also takes flags for the crypto backend, the storage backend, the remote, and a team name, which the team section uses.

gopass setup
gopass clone [email protected]:john/passwords.git

How Do You Add Your First Secrets?

Your first secret takes one command, and the name is a path. The gopass insert command prompts twice for the secret, then asks you to confirm the recipients it will encrypt for. Use a path that mirrors the service, such as an email folder plus a domain, so the store stays organised as it grows.

Generated passwords are the safer habit for new accounts. The generate command asks for a length and defaults to 20 characters, and a length argument sets it directly. Four generators exist: cryptic, memorable, xkcd, and external, and the print flag shows the password instead of copying it to the clipboard.

gopass insert example.com/user
gopass generate example.com/user 16
gopass create

The create command opens an interactive wizard that asks for the entry name and walks through the options. Secrets can also hold structure: the first line is the password, and the lines after a three-dash separator can hold YAML keys such as a username or a one-time-password secret. A template file in a folder applies automatically when you edit a new secret inside that folder.

How Do You Find, Show, and Edit Secrets?

Daily use is four verbs: list, find, show, and edit. The list command prints the store as a tree, find runs a fuzzy search when no literal match exists, and show decrypts one entry. The table below is the daily command set, and it is worth learning by heart before you add a second secret.

The clipboard flag copies the password and clears it after 45 seconds by default. Show with the password-only flag prints just the password line, which is handy for scripts, and the bare name on its own is a shortcut for show. Secrets also support one-time passwords, with TOTP and HOTP from an otpauth URL or a YAML totp key.

Editing opens the secret in your editor, inside a secure temporary directory. The Neovim beginner guide on CodexFuse covers the editor many terminal users pair with this command, and the editor variable decides which editor opens. Do not store one-time-password secrets alongside the passwords they protect, and keep them in a separate store instead.

Two more commands close the daily loop. The audit command checks stored passwords for flaws offline, and a separate integration checks them against leaked-password lists. The doctor command checks the binary dependencies, the git configuration, the store permissions, and whether every recipient key is still valid.

How Does the Git Lesson Work?

A gopass git password store is a plain git repository, and that is the whole mental model. Each secret is one GPG-encrypted file, the directory layout is the organisation, and every change is a commit. If you can read a git log, you can read the history of every password you own.

Gopass pushes changes to the default remote after every write, so a new secret lands on the server without a second command. Pulling is the other half, and the sync command does both: it pulls, pushes, and exchanges any missing GPG keys across every mounted store. Pull and push also exist as separate commands for one store at a time.

The passthrough runs any git command inside the store, and the 1.12.0 changelog marked it deprecated, but it is still documented in the v1.17.4 man page. Prefer sync, pull, and push for everyday work, and keep the passthrough for inspection commands such as the log. The revision flag on show prints a past version of one entry, so a bad edit is one command away from recovery.

Use a private git repository for the store. A public one keeps the credentials secure, because the files are encrypted, but it leaks metadata such as service names and change times, and the official docs say so plainly. The plain-filesystem storage option exists for users who prefer a synced folder instead of git, but the docs warn that cloud storage may hurt the confidentiality of the store.

Two people editing the same secret can produce a merge conflict inside an encrypted file, and the README documents no conflict-resolution workflow for that case. Teams should agree that one person owns each secret at a time, and the team section below shows how recipients make that ownership explicit.

How Does Team Password Sharing Work?

Gopass team password sharing works through recipients, and every secret is encrypted to every recipient listed in the store. Add a teammate's GPG key and the whole store re-encrypts so they can read it. Remove a key and the store re-encrypts so they cannot, which is the whole access model in one sentence.

Onboarding a new member takes three steps. Import their public GPG key, add it as a recipient, and give them access to the remote git repository that hosts the store. They then clone the remote onto their machine, and they can decrypt only because they are already a recipient, which is why the key must be added before the clone.

Mounts let one gopass hold several stores at once, and sub-stores are addressed transparently by path. A team store can sit beside a personal store, and a move command can copy a secret across stores. The recipients command also loads and saves missing public keys from the store itself, so keys travel with the repository.

Scripted setup covers the whole bootstrap in one line. The first command creates a shared store and pushes it to an empty remote, and every other team member runs the second line to join it. The team flag used to be called alias, and the old name still works, but the current flag is team.

gopass --yes setup --remote github.com/example/pass.git --team example --create-team --name "John Doe" --email "[email protected]"
gopass --yes setup --remote github.com/example/pass.git --team example --name "Jane Doe" --email "[email protected]"

The project describes itself as built for teams, on multiple devices or fully offline on an air-gapped machine. No network is required unless you want it, and the git remote is the only piece that ever touches a server. That is the reason teams pick this tool over a browser vault: the store is files, the history is git, and the sharing is encryption.

gopass vs pass: Which One Fits You?

Gopass vs pass is a short comparison, because gopass started as a Go rewrite of pass. It reads and writes the same on-disk format, a directory of GPG-encrypted files with clear-text filenames, so a pass store works with gopass as it is. You can even symlink pass to gopass and keep your old habits, which is why the project calls itself a drop-in replacement.

The difference is everything pass does not do. Gopass adds recipient management, multiple stores and mounts, built-in one-time passwords, several crypto backends, a JSON API for browser integration, fuzzy search, sync, and a REPL shell. The table below lines the two up feature by feature, and the current docs list gopass features with their states only, so this table presents what gopass adds rather than quoting an official side-by-side that no longer exists.

Pass keeps one advantage: a more extensive plugin system, in the official docs' own words. Gopass answers with integrations instead, including a browser plugin, a JSON API, a leaked-password checker, a git credential helper, a kubectl plugin, a Terraform provider, and chezmoi. If you live on Unix and love plugins, pass is still a fair pick, and if you want teams, mounts, and sync, gopass is the pick.

What Is the gopass age Backend?

The gopass age backend swaps GPG for age, a modern file-encryption tool with single key pairs and no keyring or web of trust. New users without GPG keys can start with the crypto flag at setup, and an existing store converts with the convert command. GPG stays the default, and age is the simpler on-ramp for people who have never made a key.

gopass setup --crypto=age
gopass convert --crypto age

Age has honest caveats, and the man page states them plainly. Added identities are added as recipients when encrypting, but not to the recipients list, so you must keep your recipients and identities in sync yourself. Listing recipients is not supported for the age backend, SSH keys can serve as age identities, decryption runs single-threaded, and the 1.17.4 age agent reports how long until auto-lock, supports hardware-backed keyring unlocking, and caches unlocked SSH identities.

A related tool is worth one line: passage is a fork of pass that uses age instead of GnuPG, and gopass has some support for passage but cannot be used fully interchangeably with it today. If your team already uses GPG, stay with GPG, and if you are starting fresh with no keys, age is the shorter road.

Seven Mistakes Beginners Make

Most gopass failures come from the same seven mistakes, and all seven are avoidable. The table below pairs each mistake with the fix, and the first two rows are the ones that waste the most time. Read it once before your first store, and check it again before you invite a teammate.

The Numbers Behind This Guide

Every worked number in this guide comes from the script below, run on 7 November 2026. The inputs are the GitHub API values for the gopasspw/gopass repository and the publication dates of the two independent walkthroughs. Nothing here is estimated, and no number comes from memory.

from datetime import date
today = date(2026, 11, 7)
def days(d):
    return (today - d).days
print("v1.17.4 age in days:", days(date(2026, 10, 10)))
print("repo age in days:", days(date(2017, 2, 2)))
print("repo age in years:", round(days(date(2017, 2, 2)) / 365.25, 1))
print("days since last push:", days(date(2026, 11, 5)))
print("stars per fork:", round(7316 / 569, 2))
print("open issues per 100 stars:", round(87 / 7316 * 100, 2))
print("releases per year:", round(106 / (days(date(2017, 2, 2)) / 365.25), 1))
print("commits per year:", round(2407 / (days(date(2017, 2, 2)) / 365.25), 1))
print("hceris age in days:", days(date(2018, 4, 15)))
print("hceris age in years:", round(days(date(2018, 4, 15)) / 365.25, 1))
print("ajtech age in days:", days(date(2023, 3, 18)))
print("ajtech age in years:", round(days(date(2023, 3, 18)) / 365.25, 1))
print("days from v1.16.0 to v1.17.4:", (date(2026, 10, 10) - date(2025, 11, 12)).days)
print("v1.16.1 age in days:", days(date(2025, 12, 13)))

Output:
v1.17.4 age in days: 28
repo age in days: 3565
repo age in years: 9.8
days since last push: 2
stars per fork: 12.86
open issues per 100 stars: 1.19
releases per year: 10.9
commits per year: 246.6
hceris age in days: 3128
hceris age in years: 8.6
ajtech age in days: 1330
ajtech age in years: 3.6
days from v1.16.0 to v1.17.4: 332
v1.16.1 age in days: 329

The freshness gap is the reason this guide exists. The closest independent walkthroughs are 3,128 days old, or 8.6 years, and 1,330 days old, or 3.6 years, and the older one leads with the init syntax while the newer one predates the doctor command, the age-agent improvements, the secret-service daemon, and the 1.16 and 1.17 releases. No unified fresh walkthrough was found in this research, and the 2026 overview from HelpNetSecurity is news, not a walkthrough.

Sources

The repository facts come from the GitHub API for gopasspw/gopass, fetched on 7 November 2026: 7,316 stars, 569 forks, 87 open issues, MIT license, created 2 February 2017, last push 5 November 2026, Go as the primary language. The latest release comes from the releases API: v1.17.4, published 10 October 2026, with the changelog on the release page, including the age-agent improvements, the Linux Secret Service daemon, and the path-traversal and symlinked-entry fixes.

The install routes, the setup wizard, the GPG key flow, the git sync, and the team bootstrap come from the project README and the docs setup and features pages on the master branch, fetched on 7 November 2026. The command list, the setup and init flags, the age backend caveats, and the secret-service daemon come from the v1.17.4 man page. The Debian trap comes from the README warning and Debian bug 1108303, which records the removal of the unrelated Debian gopass package from unstable in June 2025.

The freshness check comes from the two independent walkthroughs: the hceris.com guide published 15 April 2018, and the ajtech.nl guide published 18 March 2023. The pass comparison draws on the codecentric team guide and the project features page, and the 2026 overview from HelpNetSecurity, published 21 September 2026, confirms the drop-in-replacement framing and the install routes. No testbed outputs were executed for this guide, and no Facebook promotion applies to this article.

Frequently Asked Questions

Is gopass free?

Yes, gopass is free and open source under the MIT license, and the code lives at github.com/gopasspw/gopass. There is no paid tier in the project itself, and the tool runs fully offline unless you choose to sync through a git remote.

Do I need GPG to use gopass?

By default, yes, because GPG encrypts every secret and git versions the store. If you have no GPG key, the age backend is the alternative, and gopass setup with the age crypto flag starts a store with no keyring at all.

What is the difference between gopass setup and gopass init?

Setup is the current documented entry point in the README and the v1.17.4 man page, and it opens an interactive wizard that picks a key and asks for a git remote. Init still exists in v1.17.4, and the docs and homepage still show it in places, so older guides are not wrong, but setup is the command this guide teaches.

Can I use gopass with my existing pass store?

Yes, because gopass is a drop-in replacement for pass and reads the same on-disk format, a directory of GPG-encrypted files with clear-text filenames. A pass store works with gopass as it is, and you can even symlink pass to gopass if you want your old commands to keep working.

How do I share passwords with my team using gopass?

Import each teammate's public GPG key, add it with the recipients add command, and let the store re-encrypt for the new recipient. Your teammates then clone the git remote, and they can decrypt only because they are already recipients, so the key must be added before the clone.