Last update: 2024-05-06
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, 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 v27.0, so that’s the latest Bitcoin version, and it’s 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. However, this practice is discouraged because it’s far more complicated compared with getting a pre-compiled package. 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 cryptographic signatures which you can verify 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 is built for your operating system and instruction set architecture. I’m running Linux and I have an AMD CPU, so I need an x86_64-linux-gnu version:
curl --output bitcoin-27.0.tar.gz https://bitcoincore.org/bin/bitcoin-core-27.0/bitcoin-27.0-x86_64-linux-gnu.tar.gz
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-27.0.tar.gz --verbose
You should see the following output:
bitcoin-27.0/
bitcoin-27.0/README.md
bitcoin-27.0/bin/
bitcoin-27.0/bin/bitcoin-cli
bitcoin-27.0/bin/bitcoin-qt
bitcoin-27.0/bin/bitcoin-tx
bitcoin-27.0/bin/bitcoin-util
bitcoin-27.0/bin/bitcoin-wallet
bitcoin-27.0/bin/bitcoind
bitcoin-27.0/bin/test_bitcoin
bitcoin-27.0/bitcoin.conf
bitcoin-27.0/include/
bitcoin-27.0/include/bitcoinconsensus.h
bitcoin-27.0/lib/
bitcoin-27.0/lib/libbitcoinconsensus.so
bitcoin-27.0/lib/libbitcoinconsensus.so.0
bitcoin-27.0/lib/libbitcoinconsensus.so.0.0.0
bitcoin-27.0/share/
bitcoin-27.0/share/man/
bitcoin-27.0/share/man/man1/
bitcoin-27.0/share/man/man1/bitcoin-cli.1
bitcoin-27.0/share/man/man1/bitcoin-qt.1
bitcoin-27.0/share/man/man1/bitcoin-tx.1
bitcoin-27.0/share/man/man1/bitcoin-util.1
bitcoin-27.0/share/man/man1/bitcoin-wallet.1
bitcoin-27.0/share/man/man1/bitcoind.1
bitcoin-27.0/share/rpcauth/
bitcoin-27.0/share/rpcauth/README.md
bitcoin-27.0/share/rpcauth/rpcauth.py
Wow, that’s a lot of files and dirs. Let’s go through them one by one:
/bin Directory
First, let’s check that the /bin directory also exists on our target machine. That’s the path where we’re expected to place our Bitcoin executables.
ls -l /bin
lrwxrwxrwx 1 root root 7 Oct 18 21:01 /bin -> usr/bin
In many modern Linux distributions, both /bin and /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 those binaries, let’s check what they actually do:
| File | Purpose |
|---|---|
| bitcoin-cli | Command line tool which can talk to a running bitcoind or bitcoin-qt instance. |
| bitcoind | Bitcoin Core server, without GUI included. |
| 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 grind which takes a hex-encoded header and grinds its nonce until its nBits is satisfied. |
| 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. |
| 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. |
/bitcoin.conf
Most programs can be configured to better fit a particular environment and Bitcoin Core is no exception. Older versions of Bitcoin Core didn’t really have an easy way to see all the possible configuration parameters and their purpose, and that led to the introduction of the “skeleton” conf file. This file can be copied to your data directory, but it doesn’t change any configuration options, by default. You’re supposed to open this file, find the option you want to adjust, and uncomment the string which enables this option. This way, you can clearly see the default values for every possible configuration option, as well as any active overrides.
/include Directory
As usual, it’s always a good idea to check the latest Filesystem Hierarchy Standard.
/usr/include - This is where all 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:
| File | Purpose |
|---|---|
| bitcoinconsensus.h | C header file for those who want to build software using the libbitcoinconsensus.so library. |
/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 /bin, and /lib is just an alias for /usr/lib. As usual, it’s better to use /usr/local/lib in order to avoid collisions.
| File | Purpose |
|---|---|
| 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 libbitcoinconsensus.
/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 /usr/local/share directory.
| File | Purpose |
|---|---|
| man/man1/bitcoin-cli.1 | man page for bitcoin-cli binary |
| man/man1/bitcoind.1 | man page for bitcoind binary |
| man/man1/bitcoin-qt.1 | man page for bitcoin-qt binary |
| man/man1/bitcoin-tx.1 | man page for bitcoin-tx binary |
| man/man1/bitcoin-util.1 | man page for bitcoin-util binary |
| man/man1/bitcoin-wallet.1 | man page for bitcoin-wallet 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.
There is also a folder called rpcauth, and it contains a simple script used to generate JSON-RPC users.
| File | Purpose |
|---|---|
| rpcauth/README.md | Explains how to use rpcauth.py |
| rpcauth/rpcauth.py | A script used to create JSON-RPC users |
Conclusion
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:
- /bin/bitcoin-cli
- /bin/bitcoin-qt
- /share/man/man1/bitcoin-cli.1
- /share/man/man1/bitcoin-qt.1
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:
- /bin/bitcoin-cli
- /bin/bitcoind
- /share/man/man1/bitcoin-cli.1
- /share/man/man1/bitcoind.1