Migrate a GnuPG Keyring with migrate-pubring-from-classic-gpg

GnuPG dropped the old flat keyring format, and migrate-pubring-from-classic-gpg moves a public keyring from pubring.gpg to the modern pubring.kbx. The migration script makes a dated backup of the old keyring and owner trust before importing it. Allow 10 to 15 minutes, plus time to check the backup, and keep the original GnuPG home directory available until verification is complete.

1. Check the installed version and target directory

This guide covers the Debian and Ubuntu utility migrate-pubring-from-classic-gpg. On this machine it comes from gnupg-utils 2.4.4-2ubuntu17.6 and uses GnuPG 2.4.4. The installed script explicitly accepts GnuPG 2.1, 2.2 and 2.4; older or newer package builds may differ, so check before using an example in automation.

$ command -v migrate-pubring-from-classic-gpg
/usr/bin/migrate-pubring-from-classic-gpg
$ dpkg-query -W -f='${Package} ${Version}\n' gnupg-utils
gnupg-utils 2.4.4-2ubuntu17.6
$ gpg --version | head -n 1
gpg (GnuPG) 2.4.4

The script accepts one positional GnuPG home directory, or the special --default argument. The default form uses GNUPGHOME when it's set and otherwise falls back to ~/.gnupg. It never infers a different directory from your current working directory.

2. Inspect the keyring before changing it

Set a shell variable to the exact home directory you intend to migrate. Use an unprivileged shell unless that directory is deliberately locked away from your account. Don't reach for sudo as a first response to an incorrect path: it can leave the resulting files owned by root and harder to manage afterwards.

$ GPG_HOME="$HOME/.gnupg"
$ test -d "$GPG_HOME" && echo "directory exists"
directory exists
$ ls -l "$GPG_HOME/pubring.gpg"
-rw------- 1 USER USER 1234 Sep 25 01:55 /home/USER/.gnupg/pubring.gpg

The size, owner and timestamp above are examples. What matters is that the file exists and is the public keyring you actually mean to migrate. If the file is absent, don't create an empty replacement just to make the command run: the tool treats an absent keyring as no migration being needed.

3. Make a separate safety copy

The migration utility makes its own backup, but make a separate copy too if the keyring actually matters. Include the GnuPG home directory permissions and keep this copy somewhere private: the public key material isn't secret, but owner trust can disclose local trust decisions.

$ BACKUP_DIR="$HOME/gnupg-before-pubring-migration"
$ mkdir -m 700 "$BACKUP_DIR"
$ cp --preserve=all "$GPG_HOME/pubring.gpg" "$BACKUP_DIR/"
$ test -s "$BACKUP_DIR/pubring.gpg" && echo "backup is non-empty"
backup is non-empty

If the destination already exists, stop and pick another name rather than overwriting an earlier backup. Keep this copy until you've confirmed the new keybox holds the expected keys.

4. Run the migration against the explicit home directory

$ migrate-pubring-from-classic-gpg "$GPG_HOME"
Migrating from:
.../pubring.gpg
[Backing up to .../migrate-from-classic-backup.2026-09-25.XXXXXX]
gpg: key ...: public key "..." imported
Migration completed successfully:
.../pubring.kbx

The date and random suffix are generated at run time, and key fingerprints vary. What matters is the final completion message naming pubring.kbx. The command returns status 0 when the migration completes, including the normal no-op case where there's no pubring.gpg at all.

5. Verify the new keybox and the backup

Check that the new file exists, that the old file now sits below the dated backup directory, and that GnuPG can list keys from the migrated home. The fingerprint and user ID should match records you already trust.

$ test -s "$GPG_HOME/pubring.kbx" && echo "keybox exists"
keybox exists
$ find "$GPG_HOME" -maxdepth 2 -type f -name 'pubring.gpg' -print
/home/USER/.gnupg/migrate-from-classic-backup.2026-09-25.XXXXXX/pubring.gpg
$ GNUPGHOME="$GPG_HOME" gpg --batch --list-keys --with-colons
tru::1:...
pub:u:2048:1:...:...:...::u:::scSC::::::23::0:
fpr:::::::::...:
uid:u::::...::...::Example User <[email protected]>::::::::0:

Don't treat the sample fingerprint as an expected value. Compare your output against a known-good record, such as a previously saved fingerprint, and inspect the backup directory with ls -ld. A keybox existing by itself doesn't prove every certificate was accepted.

6. Handle warnings and limitations

The modern keybox rejects some certificates that the classic format happily accepted. A flooded certificate larger than 5 MiB can produce an error such as Provided object is too large. GnuPG 2.2.17 and later may retry that import after stripping third-party certifications. OpenPGPv3 public keys, also called PGP-2 keys, get skipped and can produce skipped PGP-2 keys: 1.

These messages can mean the migration is incomplete even when the script continues on with owner trust and produces a keybox. Compare the key lists before and after, then decide whether the missing material is obsolete or needs separate handling. Don't delete the dated backup while you're still investigating.

7. Recover if the result is wrong

If you need to return to the classic keyring, stop applications that use this GnuPG home and preserve the new keybox first. Then move pubring.kbx aside and copy the backed-up pubring.gpg back into the GnuPG home. Use the exact backup path the migration printed, and don't guess between several dated directories.

$ RECOVERY="$GPG_HOME/migrate-from-classic-backup.YYYY-MM-DD.RANDOM"
$ cp --preserve=all "$GPG_HOME/pubring.kbx" "$GPG_HOME/pubring.kbx.after-migration"
$ mv "$GPG_HOME/pubring.kbx" "$GPG_HOME/pubring.kbx.disabled"
$ cp --preserve=all "$RECOVERY/pubring.gpg" "$GPG_HOME/pubring.gpg"
$ GNUPGHOME="$GPG_HOME" gpg --batch --list-keys

This is a manual rollback, not an undo option the utility provides itself. Keep the new keybox and the migration backup until the rollback has been checked. If another GnuPG process is using the directory, finish or stop that process safely before touching keyring files.