Igor Bubelov

Bitcoin Release Unpacked - v29

Wed, 23 Apr 2025 00:00:00 +0000

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.

What’s Changed Since v28

I didn’t notice any changes in release bundle file names or structure. For code changes, you can check this page.

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 v29.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-29.0.tar.gz https://bitcoincore.org/bin/bitcoin-core-29.0/bitcoin-29.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-29.0.tar.gz --verbose

You should see the following output:

bitcoin-29.0/
bitcoin-29.0/README.md
bitcoin-29.0/bin/
bitcoin-29.0/bin/bitcoin-cli
bitcoin-29.0/bin/bitcoin-qt
bitcoin-29.0/bin/bitcoin-tx
bitcoin-29.0/bin/bitcoin-util
bitcoin-29.0/bin/bitcoin-wallet
bitcoin-29.0/bin/bitcoind
bitcoin-29.0/bin/test_bitcoin
bitcoin-29.0/bitcoin.conf
bitcoin-29.0/share/
bitcoin-29.0/share/man/
bitcoin-29.0/share/man/man1/
bitcoin-29.0/share/man/man1/bitcoin-cli.1
bitcoin-29.0/share/man/man1/bitcoin-qt.1
bitcoin-29.0/share/man/man1/bitcoin-tx.1
bitcoin-29.0/share/man/man1/bitcoin-util.1
bitcoin-29.0/share/man/man1/bitcoin-wallet.1
bitcoin-29.0/share/man/man1/bitcoind.1
bitcoin-29.0/share/rpcauth/
bitcoin-29.0/share/rpcauth/README.md
bitcoin-29.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.

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

Bitcoin Release Unpacked - v28

Mon, 07 Oct 2024 00:00:00 +0000

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

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

Extracting Files From Release Archive

curl --output bitcoin-28.0.tar.gz https://bitcoincore.org/bin/bitcoin-core-28.0/bitcoin-28.0-x86_64-linux-gnu.tar.gz

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

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

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

/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

Bitcoin Release Unpacked - v27

Fri, 17 Jun 2022 00:00:00 +0000

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.

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

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

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

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

/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.

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

Igor Bubelov

Bitcoin Release Unpacked - v29

Table of Contents

What’s Changed Since v28

Where to Find the Latest Release

Building From Source vs Getting Binaries

Extracting Files From Release Archive

/bin Directory

/bitcoin.conf

Conclusion

Bitcoin Release Unpacked - v28

Table of Contents

What’s Changed Since v27

Where to Find the Latest Release

Building From Source vs Getting Binaries

Extracting Files From Release Archive

/bin Directory

/bitcoin.conf

Conclusion

Bitcoin Release Unpacked - v27

Table of Contents

Where to Find the Latest Release

Building From Source vs Getting Binaries

Extracting Files From the Archive

/bin Directory

/bitcoin.conf

/include Directory

/lib Directory

Conclusion

Igor Bubelov

Bitcoin Release Unpacked - v29

Table of Contents

What’s Changed Since v28

Where to Find the Latest Release

Building From Source vs Getting Binaries

Extracting Files From Release Archive

/bin Directory

/bitcoin.conf

/share Directory

Conclusion

Bitcoin Release Unpacked - v28

Table of Contents

What’s Changed Since v27

Where to Find the Latest Release

Building From Source vs Getting Binaries

Extracting Files From Release Archive

/bin Directory

/bitcoin.conf

/share Directory

Conclusion

Bitcoin Release Unpacked - v27

Table of Contents

Where to Find the Latest Release

Building From Source vs Getting Binaries

Extracting Files From the Archive

/bin Directory

/bitcoin.conf

/include Directory

/lib Directory

/share Directory

Conclusion