Migrate a classic GnuPG keyring to pubring.kbx safely

You will move a GnuPG public keyring from the old pubring.gpg format to the modern pubring.kbx format. 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 is set and otherwise falls back to ~/.gnupg. It does not infer a different directory from the 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 inaccessible to your account. Do not use sudo as a first response to an incorrect path: it can make the resulting files owned by root and harder to manage.

$ 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 in the listing are examples. The useful check is that the file exists and is the public keyring you mean to migrate. If the file is absent, do not 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 creates its own backup, but make a separate copy if the keyring matters. Include the GnuPG home directory permissions and keep this copy somewhere private. The public key material is not 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 choose another name rather than overwriting an earlier backup. Keep this copy until you have confirmed that the new keybox contains 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. The important result 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 is no pubring.gpg.

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:

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

6. Handle warnings and limitations

The modern keybox rejects some certificates that the classic format 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, are skipped and can produce skipped PGP-2 keys: 1.

These messages can mean that the migration is incomplete even when the script continues with owner trust and creates a keybox. Compare the key lists before and after, then decide whether the missing material is obsolete or needs separate handling. Do not delete the dated backup while 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 to the GnuPG home. Use the exact backup path printed by the migration, and do not guess among 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 provided by the utility. 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 changing keyring files.