Navigation Menu

Skip to content

Instantly share code, notes, and snippets.

Last active November 8, 2022 01:55
Show Gist options
  • Star 4 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save niftynei/89c60e21380794b1779a3f6190dd141d to your computer and use it in GitHub Desktop.
Save niftynei/89c60e21380794b1779a3f6190dd141d to your computer and use it in GitHub Desktop.


Getting a copy

At time of writing, bitcoind is available on Github at If you'd like, you can clone the repository and build the project from source.

The easier and faster way to get bitcoind working is to download a pre-built binary. has an update list of them: If you download a pre-built version it is strongly recommended that you verify the binary. There are instructions on how to do so currently on the download page.

If you skip this part, it's not a problem for this class. We won't be putting any real bitcoin on your installation.

bitcoind networks

There are currently three different 'networks'* you can run bitcoind against: mainnet, testnet, and regtest.

* A fourth, called 'signet' also exists, but we're going to pretend it doesn't for now.

  • mainnet is the global network that 'real' bitcoins are mined and transacted on. This network requires an 'initial block sync' in order for bitcoind to be fully operational. This means that the computer running bitcoind will download the entire Bitcoin blockchain from other peers on the mainnet network. Depending on your network connection, hardware speed, and year that you are attempting this, it can take up to two weeks to fully download and verify the current blockchain. Additionally, it will require somewhere from 200 to 500GB of space.*
  • testnet is the global test network. The bitcoins that are mined and transacted on this network have no value; typically they're denoted as tBTC. This network is meant to be used to test software on. As it is a global network with a blockchain, it also requires an initial block sync in order to be operational. Typically, testnet is smaller than the mainnet blockchain, but it can still take several hours for the sync to complete.
  • regtest is a local testing environment for bitcoind. The blockchain is entirely local to the machine running bitcoind. No initial block sync is required in order to set up. ('reg' in 'regtest' stands for 'regression' as in 'regression testing'). Every time you start up a new regtest version of bitcoind is identical. This is the mode that we'll be running bitcoind in for the examples in this book.

* Note that it's possible to use less memory, but operating your node in a 'pruned' state. Running a pruned bitcoin client is out of the scope of this document.

bitcoind, An Orientation

Bitcoind stores all of the data required for it to operate in a directory, called the datadir. By default, it's .bitcoin and located in your home directory. On my Ubuntu machine this is ~/.bitcoin. (MacOS and Windows machines will have a different filepath). This is where the blockchain data is stored, logs, mempool data, wallets, fee estimates, peers, etc. It's all here.

Bitcoind* should come with two programs, the bitcoin node software (bitcoind) and an RPC client that allows you to interact with the node (bitcoin-cli).

* The 'd' part of Bitcoind stands for 'daemon'. Traditionally, daemons are programs that run in background processes of your machine.

Both of these programs have options that you can configure. For bitcoind, place configuration options in the datadir in a file called bitcoin.conf. To see a list of all of the options that are possible, run bitcoind --help. bitcoin-cli also has a list of options available. Similarly, you can list them with bitcoin-cli --help.

There are two ways to pass options to bitcoind. You can either places them in a configuration file (the default location for this is in a file called bitcoin.conf in the .bitcoin directory) or pass them via the command line when you start the program.

Note: bitcoin-cli by default uses the same config file as bitcoind. If you set up the config file as listed below, you won't need to use the -regtest flag when making bitcoin-cli calls.

For the exercises in this book, we're going to configure bitcoind to run as a daemon (which means in the background) and in regtest mode. Here's a ~/.bitcoin/bitcoin.conf file with 'daemon' and 'regtest' options:



The place to put your bitcoin.conf file on a MacOSX is /Users/<username>/Library/Application Support/Bitcoin/bitcoin.conf. It's very likely this file won't exist yet. You should create it.


If you're running this on Windows, you'd want to leave the daemon option off. Your bitcoin.conf will look like:


Your data directory will probably be C:\Users\<username>\AppData\Roaming\Bitcoin. Create a file called bitcoin.conf in this directory. (So C:\Users\<username>\AppData\Roaming\Bitcoin\bitcoin.conf). Then you can start the bitcoind daemon and any configurations in this file should be applied.

Note that it's very likely the bitcoin.conf file doesn't exist yet. You should create it.

The easiest way to find the data directory is to run bitcoind -regtest, then

$ bitcoin-cli -regtest getrpcinfo

Starting bitcoind

You can start bitcoind then, like so:

$ bitcoind
> Bitcoin server starting

Alternatively, here's how to start bitcoind with these options turned on, without setting up a config file.

$ bitcoind -daemon -regtest -fallbackfee=0.00001
> Bitcoin server starting

Once bitcoind is running, we can use bitcoin-cli to interact with it. We can verify that bitcoind is up and working and that bitcoin-cli is talking to it correctly by the following command (again, if you've set up the config file, like above, you can omit the -regtest). For the rest of the examples in this book, we assume that you've configured bitcoind and bitcoin-cli using the config file shown previously.

$ bitcoin-cli -regtest help
>  ... lists all of the commands

If you get the following error, make sure that bitcoind is running and is configured to run in regtest mode.

$ bitcoin-cli -regtest help
> error: Could not connect to the server
> Make sure the bitcoind server is running and that you are connecting to the correct RPC port.
Copy link

jnh999 commented Apr 20, 2022

For Mac setup, I also found this resource really valuable (step-by-step video walkthrough of setting up a pruned node from the pre-built version):

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment