How to sync a Bitcoin node

Learn how to sync a Bitcoin node for building Bitcoin applications.

Syncing a Bitcoin node is often one of the first steps a developer takes when building a Bitcoin application. It's a great introduction to the Bitcoin developer ecosystem, and if you're relying on on-chain data, there's no safer way to get that data than doing it yourself.

In this guide, you will learn how to:

  1. Download Bitcoin Core daemon on your machine
  2. Configure bitcoind
  3. Start syncing your node
  4. Properly shutdown and restart your node

To get started, we first need to download bitcoind. In our example, we'll be using version 25.0. You can select a software version compatible with your device from this list.

Configure bitcoind

Once your download is complete, make note of your path to the bitcoind executable.

When you sync your node, we'll be running the program at /bitcoin-25.0/bin/bitcoin, which is where the bitcoind executable is located.

Next up is a couple configuration steps.

  1. Select or create a directory to store your Bitcoin data.
  2. Update the bitcoin.conf file to include the path to your Bitcoin data directory.

The Bitcoin chainstate is pretty large, and you need a place to store it. In this example, we are going to set up a directory called bitcoin-data on an external hard drive that we have mounted at /Volumes/SSD.

This folder, bitcoin-data, can be named whatever you like, and can exist locally or in an external hard drive.

The most important thing is that it should exist in a place that has enough storage to hold all the Bitcoin data we will be receiving once it starts to sync.

Now navigate to your bitcoin.conf file, which is located in your /path/to/bitcoin directory and update the datadir field with your directory.

In this example, it would look like this:


If you plan to use your node to receive transactions, you will need to make note of the username and password fields for your node.

In the example bitcoin.conf above, devnet is listed as the default username and password.

Run the node

With a finished bitcoin.conf file, it's time to start up your node.

This takes the form of path/to/bitcoind -conf=path/to/bitcoin.conf, which in this example looks like:

/Volumes/SSD/bitcoin-25.0/bin/bitcoind -conf=/Volumes/SSD/bitcoin-25.0/bitcoin.conf

After running this command, you will see zmq_url entries in your console's stdout, displaying ZeroMQ logs from your Bitcoin node. Congrats! You're now syncing!

It might take anywhere from a few hours to a few days to run and fully sync, depending on if it's your first time syncing a node.

Proper shutdown and restart procedure

  1. Shutting down your node
  2. Restarting your node

To shut down your node safely, use the bitcoin-cli executable, located inside of the bin directory, and run the stop command:

/path/to/bitcoin-cli \
  --conf=/path/to/bitcoin.conf \
  --rpcuser={{your-rpc-username}} \
  --rpcpassword={{your-rpc-password}} stop

To start your node back up, all you need to do is refer to the previous steps from above by running path/to/bitcoind -conf=path/to/bitcoin.conf.

How to eject an external hard drive
  1. Go to the Finder, then the sidebar, and select the disk you want to eject under “Devices”. Click on the eject icon next to the name.
  2. Wait for a confirmation message saying it's safe to eject the device before you unplug the drive.

Next steps