GPG 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 = "[email protected]"

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 = "[email protected]"

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:

Prompt for the passphrase on first run of chezmoi init
Remember the passphrase in your configuration file
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

encryption = "gpg"

[gpg]
    recipient = "[email protected]"

Encrypting Specific File Types

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 = "[email protected]"
    args = ["--quiet"]

Custom GPG Arguments

You can pass additional arguments to GPG:

~/.config/chezmoi/chezmoi.toml

[gpg]
    recipient = "[email protected]"
    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 = "[email protected]"
    args = [
        "--recipient", "[email protected]",
        "--recipient", "[email protected]"
    ]

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 [email protected] > 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 [email protected]

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 [email protected]
# 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

Backup your keys: Export and securely store your GPG keys
Use subkeys: Create separate subkeys for encryption
Set expiration: Use key expiration dates for better security
Test decryption: Verify you can decrypt before removing originals
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

Get Started

Core Concepts

User Guide

Encryption & Secrets

Password Managers

Advanced Usage

FAQ

Quick Start

Asymmetric (Private/Public Key) Encryption

How It Works

Symmetric Encryption

Encrypting with a Passphrase

Usage Examples

Encrypting Files

Editing Encrypted Files

Different Recipients Per Machine

Encrypting Specific File Types

Muting GPG Output

Custom GPG Arguments

Using a Specific GPG Key

Multiple Recipients

Setting Up GPG Keys

Generate a New Key

List Your Keys

Export Your Public Key

Import a Key on Another Machine

Troubleshooting

”no public key” Error

“decryption failed” Error

Trust Issues

Permission Denied

Best Practices

GPG vs age

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

User Guide

Encryption & Secrets

Password Managers

Advanced Usage

FAQ

​Quick Start

​Asymmetric (Private/Public Key) Encryption

​How It Works

​Symmetric Encryption

​Encrypting with a Passphrase

​Usage Examples

​Encrypting Files

​Editing Encrypted Files

​Different Recipients Per Machine

​Encrypting Specific File Types

​Muting GPG Output

​Custom GPG Arguments

​Using a Specific GPG Key

​Multiple Recipients

​Setting Up GPG Keys

​Generate a New Key

​List Your Keys

​Export Your Public Key

​Import a Key on Another Machine

​Troubleshooting

​”no public key” Error

​“decryption failed” Error

​Trust Issues

​Permission Denied

​Best Practices

​GPG vs age

​See Also

Build docs developers (and LLMs) love

Quick Start

Asymmetric (Private/Public Key) Encryption

How It Works

Symmetric Encryption

Encrypting with a Passphrase

Usage Examples

Encrypting Files

Editing Encrypted Files

Different Recipients Per Machine

Encrypting Specific File Types

Muting GPG Output

Custom GPG Arguments

Using a Specific GPG Key

Multiple Recipients

Setting Up GPG Keys

Generate a New Key

List Your Keys

Export Your Public Key

Import a Key on Another Machine

Troubleshooting

”no public key” Error

“decryption failed” Error

Trust Issues

Permission Denied

Best Practices

GPG vs age

See Also