GnuPG: building the GNU Privacy Guard from its source tree

The GitHub repository is a mirror and says so

The first line of the project description is a warning, and it is unusual to see it stated this bluntly. The maintainers are not tracking this mirror. Do not make pull requests here, nor comment any commits, submit them the usual way to the bug tracker or to the mailing list.

The canonical home is on the GnuPG project's own git, reachable through the gitweb interface linked as the project homepage, and the GitHub copy is a read-only view of it. That distinction matters for anyone who arrives from a search result, finds an issue and assumes a pull request is the way to fix it.

The project itself is the GNU Privacy Guard, described as a complete and free implementation of the OpenPGP standard as defined by RFC4880. It enables encryption and signing of data and communication, and it carries a key management system plus access modules for public key directories. Starting with version 2 it also provides support for S/MIME and Secure Shell in addition to OpenPGP, which is the part that makes it useful as a general cryptographic agent rather than only an OpenPGP tool.

The licence is GPL-3.0, and the source tree carries the full set of licence files you would expect, including the GPL, the LGPL in two versions, a CC0 file and a COPYING.other file, along with an autotools build, a tests directory, a translations directory, and separate source directories for the agent, the keybox, the directory manager, the smart card and TPM daemons and the key generation tools.

The mirror is not archived and the last push was on 2026-10-19, so the code is moving even though the repository has no GitHub releases.

Five sibling libraries, in order

The build instructions start by naming what GnuPG depends on, and the list is short enough to be worth quoting. GnuPG 2.6 depends on the GnuPG related packages npth, libgpg-error, libgcrypt, libksba and libassuan, each with its own download location under the gcrypt directory of the project's FTP site.

The instruction is to build and install them in the order given, and the reasoning is visible in the text: the configure script complains if a version is not sufficient. So the failure mode of skipping the order is a configure error rather than a mysterious link failure, which is a kindness.

Several other standard libraries are also required, and the script prints diagnostic messages when one of them is missing so that the corresponding feature is simply not available rather than the build stopping. That is a pattern worth noting: GnuPG degrades by dropping features, so a successful build does not necessarily mean you have smartcard support, or LDAP keyserver support, or anything else that depends on an optional library.

There is one more runtime component that is not a build requirement. You need the Pinentry package for most functions of GnuPG, and it is not needed to build it. Pinentry is the separate graphical or curses program that asks for your passphrase, and keeping it out of the build graph is what lets GnuPG be linked into a daemon, a library or a service where asking for a passphrase on a terminal makes no sense.

The ordinary build, and the Speedo shortcut

The standard build is the familiar autotools sequence, and it is worth reading the extra notes rather than skipping them.

mkdir build
cd build
../configure
make
make check
make install

The make check step is described as optional but highly recommended, and there is a way to run more of the test suite by adding the enable-all-tests option to the configure run. You might need to become root before the install step, and if everything succeeds you have a working GnuPG with support for OpenPGP, S/MIME, ssh-agent and smartcards.

The Speedo target exists to build everything without installing the dependencies first. On a Debian based system the toolchain is installed with apt-get, and the list of packages is specific:

apt-get install build-essential libusb-1.0-0-dev libsqlite3-dev \
                    libldap-dev libreadline-dev patchelf

The note says that the LDAP and readline development packages are not strictly necessary but are highly suggested. Then, as a regular user, you run the native target:

make -f build-aux/speedo.mk native

That downloads the required libraries and does a native build into a directory named PLAY, and the whole thing can then be installed into an arbitrary location with a system root argument:

make -f build-aux/speedo.mk install SYSROOT=/usr/local/gnupg26

Two details in that procedure matter. The tarball variant needs only a different make invocation, and the advantage of that tarball is that all libraries are included so the Makefile does not need to download new ones. In either case, the documentation is explicit that all downloaded files come with signatures which are verified by the Makefile commands, and that the patchelf command is required to rewrite the shared library search path in the binaries to relative directories.

Daemons, sockets and the directories they share

GnuPG is not one binary. The source tree is organised around a set of cooperating daemons, and understanding which is which explains most of the operational surprises.

The tree has separate directories for the agent, the keybox, the directory manager, the smart card daemon, the TPM 2.0 daemon and the key generation utilities, alongside the common code, the tools and the tests. The configuration and the runtime directories can be inspected from the command line:

gpgconf -L

The point of that command is to show you the directories GnuPG is actually using, which is the first thing to check when a key is not where you expect it, when a second instance refuses to start, or when a system-wide configuration is being read instead of your own.

The daemons also explain the recommendation about using a different home directory when running an installed build from a custom system root. The documentation warns you to make sure to stop any already running daemons or to use a different GNUPGHOME, because a daemon started by one installation will keep serving requests from another, and the symptoms of that are confusing because the client and the daemon can disagree about paths and configuration.

There is also a Windows-specific note in the build instructions. Instructions for building an installer for Windows live in a hacking document and the documentation is upfront that this requires some experience as a developer.

keyboxd moves public keys into SQLite

The most substantive operational change in recent versions is the key database daemon, and it is the recommendation that matters most for anyone building from source.

Since version 2.3.0 it is possible to store the keys in an SQLite database instead of the keyring.kbx file. The documentation gives the reason: it is particularly useful for large keyrings, or if many instances of gpg and gpgsm may run concurrently. It is implemented as a separate daemon process called the keyboxd, and you enable it by putting the use-keyboxd option into the configuration file in your own home directory, in the common.conf file, or in the global one under /etc/gnupg.

The scope of the daemon is limited in a way that is easy to miss. Only public keys and X.509 certificates are managed by the keyboxd. Private keys are still stored as separate files. So moving to the daemon changes where your public keyring lives, and it does not change how your secret keys are protected.

Since version 2.4.1 the keyboxd is used by default for a fresh install, meaning a home directory that did not yet exist. For an existing installation nothing changes until you opt in, and the documentation is explicit that there is no automatic migration, so an existing keyring file stays where it is until you move it yourself.

The concurrency argument is the real motivation. A single file that many processes read and write is a contention point, and SQLite with a dedicated daemon gives each client a clean interface to a database that one process owns. If you are running a machine with many gpg invocations, that is the difference between a keyring that scales and one that does not.

Windows, Cygwin and a compiler without C99

The build instructions carry a section of specific problems on some machines, and each entry is a workaround for a real detection failure rather than a general tip.

On some versions of Apple macOS with Xcode, the correct location of a header file cannot be detected by configure, and the fix is to pass the location explicitly:

./configure  gl_cv_absolute_stdint_h=/usr/include/stdint.h

Cygwin, described as Posix emulation on top of Windows, is not officially supported, but GnuPG can be built for that platform, and it might require:

./configure  ac_cv_type_SOCKET=no

For systems without a full C99 compiler, where the compiler complains about a source file called dns.c, the option is:

./configure --disable-libdns

The first two are configure cache variables that short-circuit a failed test, which is a good way to read them. The header lookup has a wrong answer, the socket type test does not work under emulation, and the DNS code needs something a pre-C99 compiler cannot provide. Understanding which failure you are suppressing matters more than knowing the flag.

The Windows configuration deserves a separate note because it is a security recommendation rather than a build fix. The Windows version of GnuPG expects optional global configuration files in %ALLUSERSPROFILE%\GNU\etc\gnupg, and current Windows versions allow all users to write to that directory by default. On a machine shared with several users, the recommendation is to secure the whole directory tree by disallowing regular users to create files or directories in it. The gpgconf -X command checks for the proper permissions and emits a warning if this has not been done, and the fix from an administrators terminal is an integrity level change on the directory.

Version numbers that disagree with each other

One inconsistency in the documentation is worth flagging before you pin a version.

The readme header identifies itself as version 2.5, and the note underneath says that this is the stable version of GnuPG. The build instructions, however, refer to GnuPG 2.6, and the Speedo install example uses a system root named for gnupg26, and the dependency list is introduced as the list for 2.6.

So the readme mixes a 2.5 banner with 2.6 build guidance. That is the sort of drift that happens when a version banner is updated less often than the instructions, and it means the authoritative version is whichever the configure script reports, not the banner at the top of the file. The sensible move for anyone building from source is to read the version out of the built binary and record it, rather than trusting the readme.

The licensing picture is clear and worth restating because it is a GPL-3.0 project with a long history: it is Free Software that can be freely used, modified and distributed under the terms of the GNU General Public License. The copyright lines in the readme also show the project's history, with the original author, the Free Software Foundation and a company called g10 Code GmbH holding copyright in successive periods, which is a reminder of how long this codebase has been maintained.

If you need advice, the documented route is the users mailing list, and the bug tracker is the place for anything that should be tracked rather than discussed.

Editorial conclusion

Building GnuPG from source is worth it when you need a version your distribution does not ship, when you are working on the daemon components such as the keybox database or the TPM interface, or when you are packaging it yourself. For ordinary use, the packaged version is the sane choice, because the Speedo build assumes a Debian-like environment and the configure script has platform specific workarounds that exist for a reason. Before you start, read the build instructions for your platform, install the five required libraries in the documented order, and decide deliberately whether the keybox daemon should hold your public keys, since there is no automatic migration from the old keyring file.

Frequently asked questions

Official sources

1. gpg/gnupg on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README