GPG Encryption

Encrypt your dotfiles with GPG/PGP encryption

chezmoi supports encrypting files with GPG, also known as GnuPG. Encrypted files are stored in the source state and automatically decrypted when generating the target state or editing with chezmoi edit.

Quick Start

Configure GPG encryption in your chezmoi config:

~/.config/chezmoi/chezmoi.toml

encryption = "gpg"

[gpg]
    recipient = "[e-mail]"

Make sure encryption = "gpg" is at the top level of your config, before any other sections.

Asymmetric (Private/Public Key) Encryption

Asymmetric encryption uses your GPG key pair. Specify the encryption key recipient in your configuration:

~/.config/chezmoi/chezmoi.toml

encryption = "gpg"

[gpg]
    recipient = "[e-mail]"

Or use the key ID directly:

~/.config/chezmoi/chezmoi.toml

encryption = "gpg"

[gpg]
    recipient = "0x1234567890ABCDEF"

How It Works

chezmoi will encrypt files using:

gpg --armor --recipient $RECIPIENT --encrypt

The encrypted file is stored in the source state and automatically decrypted when generating the target state.

Symmetric Encryption

For symmetric encryption (password-based), configure:

~/.config/chezmoi/chezmoi.toml

encryption = "gpg"

[gpg]
    symmetric = true

chezmoi will encrypt files using:

gpg --armor --symmetric

Encrypting with a Passphrase

If you want to encrypt files with a passphrase that’s stored in plaintext on your machines:

~/.local/share/chezmoi/.chezmoi.toml.tmpl

{{ $passphrase := promptStringOnce . "passphrase" "passphrase" -}}

encryption = "gpg"

[data]
    passphrase = {{ $passphrase | quote }}

[gpg]
    symmetric = true
    args = [
        "--batch",
        "--passphrase", {{ $passphrase | quote }},
        "--no-symkey-cache"
    ]

This will:

1. Prompt for the passphrase on first run of chezmoi init
2. Remember the passphrase in your configuration file
3. Use it automatically for encryption/decryption

The passphrase will be stored in plaintext in your config file. Only use this if you’re comfortable with that trade-off.

Usage Examples

Encrypting Files

Add an encrypted SSH key:

chezmoi add --encrypt ~/.ssh/id_rsa

Editing Encrypted Files

Edit an encrypted file (automatically decrypts and re-encrypts):

chezmoi edit ~/.ssh/id_rsa

Different Recipients Per Machine

Personal Machine

encryption = "gpg"

[gpg]
    recipient = "[e-mail]"

Encrypting Specific File Types

SSH Keys

chezmoi add --encrypt ~/.ssh/id_rsa
chezmoi add --encrypt ~/.ssh/id_ed25519

Muting GPG Output

GPG sends some info messages to stderr instead of stdout. To mute this output, add --quiet to gpg.args:

~/.config/chezmoi/chezmoi.toml

[gpg]
    recipient = "[e-mail]"
    args = ["--quiet"]

Custom GPG Arguments

You can pass additional arguments to GPG:

~/.config/chezmoi/chezmoi.toml

[gpg]
    recipient = "[e-mail]"
    args = [
        "--quiet",
        "--trust-model", "always",
        "--armor"
    ]

Using a Specific GPG Key

If you have multiple GPG keys, specify which one to use:

gpg --list-secret-keys --keyid-format LONG

Then use the key ID in your config:

~/.config/chezmoi/chezmoi.toml

encryption = "gpg"

[gpg]
    recipient = "0x1234567890ABCDEF"

Multiple Recipients

To encrypt files for multiple recipients:

~/.config/chezmoi/chezmoi.toml

encryption = "gpg"

[gpg]
    recipient = "[e-mail]"
    args = [
        "--recipient", "[e-mail]",
        "--recipient", "[e-mail]"
    ]

Setting Up GPG Keys

If you don’t have a GPG key yet:

Generate a New Key

gpg --full-generate-key

Follow the prompts to create your key.

List Your Keys

gpg --list-secret-keys --keyid-format LONG

Export Your Public Key

gpg --armor --export [e-mail] > public-key.asc

Import a Key on Another Machine

gpg --import public-key.asc
gpg --import private-key.asc

Troubleshooting

”no public key” Error

Ensure the recipient key is in your GPG keyring:

gpg --list-keys [e-mail]

If not found, import it:

gpg --import public-key.asc

“decryption failed” Error

Verify you have the private key:

gpg --list-secret-keys

Trust Issues

If GPG complains about untrusted keys:

gpg --edit-key [e-mail]
# In the GPG prompt:
gpg> trust
gpg> 5  # Ultimate trust
gpg> quit

Or use --trust-model always in your config:

[gpg]
    args = ["--trust-model", "always"]

Permission Denied

Check GPG directory permissions:

chmod 700 ~/.gnupg
chmod 600 ~/.gnupg/*

Best Practices

1. Backup your keys: Export and securely store your GPG keys
2. Use subkeys: Create separate subkeys for encryption
3. Set expiration: Use key expiration dates for better security
4. Test decryption: Verify you can decrypt before removing originals
5. Consider age: For new setups, age is simpler and more modern

GPG vs age

Feature	GPG	age
Maturity	Very mature, widely used	Modern, actively developed
Key Management	Complex, multiple key types	Simple, single key type
Setup	Requires GPG installation	Built-in to chezmoi
Speed	Slower	Faster
Best For	Existing GPG users	New users, simple setups

See Also

• GPG website
• GPG documentation
• Encryption Overview
• age Encryption