Installation

pgpilot is a graphical key manager for GPG. This guide covers installation from GitHub releases, via NixOS home-manager, and building from source.

Prerequisites

pgpilot requires:

• GnuPG ≥ 2.2 (the gpg command must be in PATH)
• gpg-agent (usually bundled with GnuPG)
• pinentry — a pinentry program for password prompts (e.g. pinentry-tty, pinentry-gtk2, or pinentry-qt)

Verify prerequisites (Linux)

gpg --version
# Output should show GnuPG version ≥ 2.2

gpg-agent --version
# Confirm agent is available

which pinentry
# Should find a pinentry binary (or check: gpg-conf --list-dirs | grep pinentry)

If gpg is missing:

• Ubuntu / Debian: sudo apt install gpg gnupg-agent pinentry
• Fedora / RHEL: sudo dnf install gnupg pinentry
• Arch: sudo pacman -S gnupg pinentry
• NixOS: see the NixOS section below

---

Installation from GitHub Releases

1. Visit pgpilot releases
2. Download the .deb package or the .AppImage for your architecture
3. Install:

# Debian / Ubuntu
sudo dpkg -i PGPilot_x.y.z_amd64.deb

# AppImage (any distro)
chmod +x PGPilot_x.y.z_amd64.AppImage
./PGPilot_x.y.z_amd64.AppImage

---

NixOS / home-manager

pgpilot ships a Nix flake with a home-manager module. This is the recommended installation method on NixOS.

1. Add pgpilot to your flake inputs

flake.nix

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };
    pgpilot = {
      url = "github:gfriloux/pgpilot/v0.8.0";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
  # ...
}

2. Import the home-manager module

Pass inputs to your home-manager configuration and import the module:

# In your home-manager configuration
{ inputs, ... }:
{
  imports = [ inputs.pgpilot.homeModules.pgpilot ];

  pgpilot.pgpilot.enable = true;
}

This installs the pgpilot-app binary and registers the .desktop file for your desktop environment.

3. Rebuild

sudo nixos-rebuild switch

If the application launcher does not show pgpilot immediately after rebuilding, run:

kbuildsycoca6 --noincremental   # KDE

Or log out and back in.

GnuPG on NixOS

Make sure GnuPG and a pinentry are in your environment:

home.packages = with pkgs; [ gnupg pinentry-qt ];

---

Building from Source

Requirements

• Nix with flakes enabled (recommended) — the dev shell provides all dependencies
• Rust ≥ 1.80, Node.js 22, npm, cargo-tauri, webkit2gtk if building without Nix

Clone the repository

git clone https://github.com/gfriloux/pgpilot.git
cd pgpilot

Build in the Nix dev shell (recommended)

nix develop
just build     # produces .deb and .rpm in target/release/bundle/
just dev       # starts Tauri + Vite in hot-reload mode

Build without Nix

Install the system dependencies for your distribution (webkit2gtk, gtk3, libsoup3, pkg-config, clang, Node.js 22), then:

cd app && npm install
cargo-tauri build

---

Verification

Once installed, launch pgpilot:

pgpilot-app

A window should appear. Open the Diagnostic page from the sidebar — all checks should show OK or Info. If you see errors, see Troubleshooting.

---

Uninstall

.deb

sudo dpkg -r pgpilot

# home-manager — set enable = false and rebuild, or remove the option

# To also remove config:
rm -rf ~/.config/pgpilot/

pgpilot does not modify your GPG keyring. Your keys remain in ~/.gnupg/ and are not affected by uninstalling pgpilot.

---

Next steps

• Read Quickstart to create your first key
• See Key Management for detailed workflows
• Check Troubleshooting if you encounter issues