Every Bitcoin release is distributed as a single archive containing many cryptic files. In fact, you rarely need them all, but it’s important to understand the purpose of each and every file in this archive in order to pick the ones you actually need.
Table of Contents
What’s Changed Since v27
It looks like libconsensus is out, which means there are 4 less files and 2 less directories in v28. Here is a full list of removed files and dirs:
/include/
/include/bitcoinconsensus.h
/lib/
/lib/libbitcoinconsensus.so
/lib/libbitcoinconsensus.so.0
/lib/libbitcoinconsensus.so.0.0.0
Where to Find the Latest Release
Bitcoin source code is currently hosted on GitHub. When the devs feel that their code is stable enough to be used by node operators, they create a new release and bump its version number. GitHub has a nice interface which allows us to see the latest releases.
The most recent release is tagged as v28.0, so that’s the latest Bitcoin version, and that’s what we’ll download and examine in detail.
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 Release Archive
Every Bitcoin release has a link to the page where you can download an archive with pre-built binaries. You’ll see many 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 x86 CPU, so I need an x86_64-linux-gnu version:
curl --output bitcoin-28.0.tar.gz https://bitcoincore.org/bin/bitcoin-core-28.0/bitcoin-28.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-28.0.tar.gz --verbose
You should see the following output:
bitcoin-28.0/
bitcoin-28.0/README.md
bitcoin-28.0/bin/
bitcoin-28.0/bin/bitcoin-cli
bitcoin-28.0/bin/bitcoin-qt
bitcoin-28.0/bin/bitcoin-tx
bitcoin-28.0/bin/bitcoin-util
bitcoin-28.0/bin/bitcoin-wallet
bitcoin-28.0/bin/bitcoind
bitcoin-28.0/bin/test_bitcoin
bitcoin-28.0/bitcoin.conf
bitcoin-28.0/share/
bitcoin-28.0/share/man/
bitcoin-28.0/share/man/man1/
bitcoin-28.0/share/man/man1/bitcoin-cli.1
bitcoin-28.0/share/man/man1/bitcoin-qt.1
bitcoin-28.0/share/man/man1/bitcoin-tx.1
bitcoin-28.0/share/man/man1/bitcoin-util.1
bitcoin-28.0/share/man/man1/bitcoin-wallet.1
bitcoin-28.0/share/man/man1/bitcoind.1
bitcoin-28.0/share/rpcauth/
bitcoin-28.0/share/rpcauth/README.md
bitcoin-28.0/share/rpcauth/rpcauth.py
Wow, that’s a lot of files and directories. 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.
/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 many 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