How to fix error: cannot run gpg: No such file or directory in Git

GitBEGINNERMEDIUM

This error occurs when Git is configured to sign commits or tags with GPG, but the GPG program is not installed or cannot be found. The fix involves either installing GPG, configuring the correct path to the GPG executable, or disabling commit signing if not needed.

What this error means

This error indicates that Git is trying to use GPG (GNU Privacy Guard) to cryptographically sign a commit or tag, but it cannot find the GPG executable on your system. When you have commit signing enabled (via `commit.gpgsign = true` in your Git config), Git invokes the GPG program to generate a digital signature for each commit. This signature verifies that the commit was made by you and hasn't been tampered with. If GPG isn't installed, or Git doesn't know where to find it, you'll see this "cannot run gpg" error. The error commonly appears with additional messages like "gpg failed to sign the data" and "fatal: failed to write commit object", indicating the commit could not be created because the signing step failed.

How to fix "error: cannot run gpg: No such file or directory"

1Check if GPG is installed

First, verify whether GPG is available on your system:

bash

# Check if gpg command exists
which gpg

# Check the version if installed
gpg --version

If you see "command not found" or no output from which gpg, GPG is not installed or not in your PATH.

Check your Git configuration for signing settings:

bash

# Check if commit signing is enabled
git config --global commit.gpgsign

# Check what GPG program Git is trying to use
git config --global gpg.program

# List all GPG-related settings
git config --global --list | grep -i gpg

2Install GPG on your system

Install GnuPG using your system's package manager:

macOS (Homebrew):

bash

brew install gnupg

# Or install GPG Suite for GUI tools
brew install --cask gpg-suite

Ubuntu/Debian:

bash

sudo apt update
sudo apt install gnupg

Fedora/RHEL/CentOS:

bash

sudo dnf install gnupg2
# Or on older systems:
sudo yum install gnupg2

Arch Linux:

bash

sudo pacman -S gnupg

Windows:
- Download from https://gnupg.org/download/ (Gpg4win recommended)
- Or use Chocolatey: choco install gnupg
- Or use Scoop: scoop install gnupg

Verify installation:

bash

gpg --version
# Should show: gpg (GnuPG) 2.x.x

3Configure Git to use the correct GPG path

If GPG is installed but Git can't find it, configure the path explicitly:

bash

# Find where GPG is installed
which gpg
# Example output: /usr/bin/gpg or /opt/homebrew/bin/gpg

# Configure Git to use the correct path
git config --global gpg.program $(which gpg)

Platform-specific paths:

macOS with Homebrew (Intel):

bash

git config --global gpg.program /usr/local/bin/gpg

macOS with Homebrew (Apple Silicon):

bash

git config --global gpg.program /opt/homebrew/bin/gpg

macOS with GPG Suite/MacGPG2:

bash

git config --global gpg.program /usr/local/MacGPG2/bin/gpg2

Windows (Gpg4win):

bash

git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"
# Or for 64-bit installation:
git config --global gpg.program "C:/Program Files/GnuPG/bin/gpg.exe"

Verify the configuration:

bash

git config --global gpg.program

4Disable commit signing (if not needed)

If you don't need to sign commits, disable the feature:

Disable globally:

bash

git config --global commit.gpgsign false

Disable for a single repository:

bash

git config commit.gpgsign false

Make a single commit without signing:

bash

git commit --no-gpg-sign -m "Your commit message"

Remove the setting entirely:

bash

git config --global --unset commit.gpgsign
git config --global --unset gpg.program

Note: Some organizations and repositories require signed commits. Check with your team before disabling this feature.

5Set up a GPG key for signing (if keeping signing enabled)

If you want to use commit signing, you'll need a GPG key:

Generate a new GPG key:

bash

# Generate a new key (follow the prompts)
gpg --full-generate-key

# Recommendations:
# - Key type: RSA and RSA (default) or ECC
# - Key size: 4096 bits for RSA
# - Expiration: Set based on your security policy
# - Use your Git email address

List your keys:

bash

gpg --list-secret-keys --keyid-format=long

Example output:

bash

/home/user/.gnupg/pubring.kbx
-----------------------------
sec   rsa4096/3AA5C34371567BD2 2024-01-15 [SC]
      1234567890ABCDEF1234567890ABCDEF12345678
uid                 [ultimate] Your Name <[email protected]>
ssb   rsa4096/42B317FD4BA89E7A 2024-01-15 [E]

Configure Git to use your key:

bash

# Use the key ID after 'sec rsa4096/' (e.g., 3AA5C34371567BD2)
git config --global user.signingkey 3AA5C34371567BD2

# Enable commit signing
git config --global commit.gpgsign true

Export your public key (for GitHub/GitLab):

bash

gpg --armor --export 3AA5C34371567BD2

Copy the output and add it to your GitHub/GitLab GPG keys settings.

6Configure GPG_TTY for passphrase prompts

If GPG can't prompt for your key passphrase, you may see signing failures:

Set GPG_TTY environment variable:

bash

# Add to your shell config (~/.bashrc, ~/.zshrc, or ~/.profile)
export GPG_TTY=$(tty)

Apply immediately:

bash

source ~/.bashrc  # or ~/.zshrc

For macOS with pinentry-mac:

bash

# Install pinentry-mac
brew install pinentry-mac

# Configure GPG to use it
echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf

# Restart the GPG agent
gpgconf --kill gpg-agent

Test GPG signing manually:

bash

echo "test" | gpg --clearsign

If this succeeds and shows a signed message, GPG is working correctly.

7Use SSH signing instead of GPG (alternative)

Git 2.34+ supports signing commits with SSH keys, which is simpler than GPG:

Configure SSH signing:

bash

# Set the signing format to SSH
git config --global gpg.format ssh

# Set your SSH key for signing
git config --global user.signingkey ~/.ssh/id_ed25519.pub

# Enable commit signing
git config --global commit.gpgsign true

Create an allowed signers file (for verification):

bash

# Create the file
echo "[email protected] $(cat ~/.ssh/id_ed25519.pub)" > ~/.ssh/allowed_signers

# Configure Git to use it
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers

Benefits of SSH signing:
- Uses existing SSH keys (no separate GPG setup)
- Simpler key management
- Native GitHub/GitLab support
- No additional software required

8Fix broken Homebrew symlinks (macOS)

On macOS, Homebrew updates can sometimes break GPG symlinks:

Check if symlinks are broken:

bash

# See where gpg points to
ls -la $(which gpg)

# Check for broken symlinks in Homebrew
brew doctor

Relink GnuPG:

bash

# Unlink and relink
brew unlink gnupg && brew link gnupg

# Or force overwrite existing links
brew link --overwrite gnupg

Reinstall if necessary:

bash

brew reinstall gnupg

Verify fix:

bash

which gpg
gpg --version

Advanced notes

### GPG vs GPG2

On some systems, both gpg (version 1.x) and gpg2 (version 2.x) may be installed:

bash

# Check both versions
gpg --version
gpg2 --version

# If gpg2 is available, you might prefer it
git config --global gpg.program gpg2

GPG 2.x is recommended for modern systems as it has better security features and key management.

### GPG Agent Configuration

The GPG agent caches your passphrase so you don't have to enter it repeatedly:

bash

# ~/.gnupg/gpg-agent.conf
default-cache-ttl 3600      # Cache for 1 hour
max-cache-ttl 86400         # Maximum cache for 24 hours
pinentry-program /usr/bin/pinentry-curses  # Or pinentry-mac on macOS

Reload the agent after changes:

bash

gpgconf --kill gpg-agent
gpgconf --launch gpg-agent

### CI/CD Considerations

For automated pipelines, you have several options:

1. Disable signing in CI:

bash

git config --global commit.gpgsign false

2. Use a bot GPG key with no passphrase:

bash

# Generate key without passphrase
gpg --batch --gen-key <<EOF
Key-Type: RSA
Key-Length: 4096
Name-Real: CI Bot
Name-Email: [email protected]
Expire-Date: 0
%no-protection
%commit
EOF

3. Import key in CI:

bash

echo "$GPG_PRIVATE_KEY" | gpg --import

### Signing Tags

Tags can be signed separately from commits:

bash

# Create a signed tag
git tag -s v1.0.0 -m "Release version 1.0.0"

# Verify a signed tag
git tag -v v1.0.0

# Configure automatic tag signing
git config --global tag.gpgsign true

### Troubleshooting GPG Issues

Debug GPG operations:

bash

# Test GPG signing directly
echo "test" | gpg --clearsign

# Check GPG agent status
gpg-connect-agent /bye

# List all keys
gpg --list-keys
gpg --list-secret-keys

Common issues:
- "No secret key" - The key ID in Git config doesn't match any installed key
- "Unusable secret key" - Key may be expired or revoked
- "No pinentry" - Need to install and configure a pinentry program

### Multiple GPG Keys

If you have multiple GPG keys for different projects:

bash

# Set per-repository signing key
cd /path/to/work-repo
git config user.signingkey WORK_KEY_ID

cd /path/to/personal-repo
git config user.signingkey PERSONAL_KEY_ID

### Verifying Signed Commits

bash

# Verify signature on a specific commit
git verify-commit HEAD

# Show signature in log
git log --show-signature -1

# Show all commits with their signature status
git log --pretty="format:%h %G? %aN %s"
# %G? shows: G=Good, B=Bad, U=Unknown, N=None

How to fix error: cannot run gpg: No such file or directory in Git

What this error means

Typical symptoms

Common causes

How to fix "error: cannot run gpg: No such file or directory"

Advanced notes

Related errors

Official resources & further reading