Bitcoin Release Unpacked
Every Bitcoin release is distributed as a single archive containing a lot of cryptic files. In fact, you rarely need all of them, but it's pretty important to understand the purpose of each and every file in this archive in order to pick the ones you might actually need.
Table of Contents
Where to Find the Latest Release
Bitcoin’s source code is currently hosted on GitHub. When Bitcoin devs feel that their code is stable enough to be deployed in production environments, they tag it as a release and increment its version number. GitHub has a nice interface which allows us to see the latest release tags.
The most recent release is tagged as v23.0, so that’s the latest Bitcoin version, which is the most sensible thing for us to download.
Building From Source vs Getting Binaries
Since Bitcoin is an open source project, you can fetch its source code and compile it yourself. This practice is discouraged because it’s far more complicated compared with getting a pre-compiled package and it doesn’t really add any value. Some might think that building from source is safer, but it couldn’t be further from the truth. The archive with pre-built binaries is no less secure than the source code itself because it’s protected by a bunch of cryptographic signatures which you can verify independently if you suspect that your archive might have been tampered with.
Extracting Files From the Archive
Every Bitcoin release has a link to the page where you can download an archive with pre-built binaries. You’ll see a lot of archives there, but you only need the one which targets your operating system and instruction set architecture. I’m running Linux and I have an AMD CPU, so I need an
The name of the archive we just downloaded ends with
.tar.gz which is supposed to give as a hint on how to deal with this file. It’s common to assume that archives are always compressed, but you can create an uncompressed archive with a tool like
tar. Since the compression is optional, it’s a good practice to append the information about the compression method to the name of your archive. Bitcoin releases are always compressed with
gzip, so that’s the reason behind this weird file extension.
Okay, now it’s time to extract all the files from the archive we just downloaded:
tar --extract --file bitcoin-23.0-x86_64-linux-gnu.tar.gz --verbose
You should see the following output:
bitcoin-23.0/ bitcoin-23.0/README.md bitcoin-23.0/bin/ bitcoin-23.0/bin/bitcoin-cli bitcoin-23.0/bin/bitcoin-qt bitcoin-23.0/bin/bitcoin-tx bitcoin-23.0/bin/bitcoin-util bitcoin-23.0/bin/bitcoin-wallet bitcoin-23.0/bin/bitcoind bitcoin-23.0/bin/test_bitcoin bitcoin-23.0/include/ bitcoin-23.0/include/bitcoinconsensus.h bitcoin-23.0/lib/ bitcoin-23.0/lib/libbitcoinconsensus.so bitcoin-23.0/lib/libbitcoinconsensus.so.0 bitcoin-23.0/lib/libbitcoinconsensus.so.0.0.0 bitcoin-23.0/share/ bitcoin-23.0/share/man/ bitcoin-23.0/share/man/man1/ bitcoin-23.0/share/man/man1/bitcoin-cli.1 bitcoin-23.0/share/man/man1/bitcoin-qt.1 bitcoin-23.0/share/man/man1/bitcoin-tx.1 bitcoin-23.0/share/man/man1/bitcoin-util.1 bitcoin-23.0/share/man/man1/bitcoin-wallet.1 bitcoin-23.0/share/man/man1/bitcoind.1
Wow, that’s a lot of files and dirs. Let’s go through them one by one:
Inspecting /bin Directory
First, let’s check that a
/bin directory also exists on a target machine. That’s the path where we’re expected to place our Bitcoin executables.
ls -l /bin
lrwxrwxrwx 1 root root 7 Dec 7 2021 /bin -> usr/bin
In many modern distros, both
/usr/bin point to the same directory, so
/bin is just an alias for
/usr/bin. This sounds like the best place to keep your Bitcoin binaries. If you have any doubts, you can always check Filesystem Hierarchy Standard.
But wait, what about this entry?
Locally installed software must be placed within /usr/local rather than /usr unless it is being installed to replace or upgrade software in /usr.
It turns out, the best place to install Bitcoin binaries is
/usr/local/bin. Now that we know where to install them, let’s check what they actually do:
|bitcoin-cli||Command line tool which can talk to a running
|bitcoin-qt||Qt-based GUI with a built-in Bitcoin Core server.|
|bitcoin-tx||A standalone tool which can help you manage raw transactions.|
|bitcoin-util||It can provide functionality that does not rely on the ability to access a running Bitcoin Server. The only available command so far is
|bitcoin-wallet||A standalone tool which is used to manage Bitcoin Core wallet.dat files. Note that Bitcoin Core server (bitcoin-qt or bitcoind) can manage wallets by itself so this tool is completely optional.|
|bitcoind||Bitcoin Core server, without GUI included.|
|test_bitcoin||The binary that implements all of Bitcoin Core’s unit tests. It has been verified to pass all tests when this build of Bitcoin Core was created, but you can always repeat those tests if you feel like it.|
Inspecting /include Directory
As usual, it’s always a good idea to check the latest Filesystem Hierarchy Standard.
/usr/include - This is where all of the system’s general-use include files for the C programming language should be placed.
Again, it’s safer to use
/usr/local/include instead of
/usr/include in order to avoid conflicts with your package manager. We have only a single file to include and here is what it does:
|bitcoinconsensus.h||C header file for those who want to build software using the
Inspecting /lib Directory
/usr/lib includes object files and libraries. On some systems, it may also include internal binaries that are not intended to be executed directly by users or shell scripts.
It looks like
/lib follows the same pattern as
/lib is just an alias for
/usr/lib. As usual, it’s better to use
/usr/local/lib in order to avoid collisions.
|libbitcoinconsensus.so||Symlink to libbitcoinconsensus.so.0.0.0|
|libbitcoinconsensus.so.0||Symlink to libbitcoinconsensus.so.0.0.0|
|libbitcoinconsensus.so.0.0.0||Shared library that you can link your own software against. It implements the exact same script validation rules as Bitcoin Core does, thus avoiding the need to reimplement consensus logic yourself.|
So, this directory contains a single shared library and two symlinks which simply point to its location. This is a standard versioning convention, so it’s better to copy all of those files if you’re planning to use
Inspecting /share Directory
The last directory included in our release is
/share, so let’s first figure out its purpose.
Any program or package which contains or requires data that doesn’t need to be modified should store that data in /usr/share (or /usr/local/share, if installed locally)
Well, man pages aren’t supposed to be edited, so it would make perfect sense to place them in
|bitcoin-cli.1||man page for bitcoin-cli binary|
|bitcoin-qt.1||man page for bitcoin-qt binary|
|bitcoin-tx.1||man page for bitcoin-tx binary|
|bitcoin-util.1||man page for bitcoin-util binary|
|bitcoin-wallet.1||man page for bitcoin-wallet binary|
|bitcoind.1||man page for bitcoind binary|
It’s generally a good idea to install manuals for all the tools you’re planning to use because they tend to be quite informative and they don’t need an Internet connection to be accessed.
Bitcoin releases tend to contain a lot of files so it might be hard to understand what’s going on and which files are necessary for your particular use. For a casual desktop user, I’d recommend installing only the following files:
If you don’t have or don’t need a GUI and you want to run a headless node, this set of files might better fit your particular case: