Set up Bitcoin Core the right way

1. Install Bitcoin Core

Always download from the official source. Verify the checksum and signature — don't trust random mirrors.

# Download Bitcoin Core 28.0 (verify latest at bitcoincore.org)
$ wget https://bitcoincore.org/bin/bitcoin-core-28.0/bitcoin-28.0-x86_64-linux-gnu.tar.gz

# Extract and install
$ tar xzf bitcoin-28.0-x86_64-linux-gnu.tar.gz
$ sudo install -m 0755 -o root -g root -t /usr/local/bin bitcoin-28.0/bin/*

# Verify it works
$ bitcoind --version

2. Create a config file

The default config works, but these settings make a meaningful difference for a home or VPS node. Full field notes: bitcoin.conf reference.

# Reduce memory pressure during sync
dbcache=2048

# Listen for incoming connections (helps the network)
listen=1

# RPC localhost only — never expose 8332 to WAN
rpcallowip=127.0.0.1

# Optional: prune (~7-10GB block data). Omit for full node.
# prune=550

# Optional: Tor — see /guides/tor-and-privacy/
# proxy=127.0.0.1:9050
# listenonion=1

3. Start syncing

Run bitcoind as a background service. Initial sync takes hours to weeks depending on hardware and disk — varies by disk, not something we benchmark here.

$ bitcoind -daemon

$ bitcoin-cli getblockchaininfo

# verificationprogress → aim for 1.0
# blocks should approach chain tip headers

$ df -h

4. Run as a systemd service (recommended)

Starts on boot and restarts on crash.

[Unit]
Description=Bitcoin daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/bitcoind -daemonwait=1
ExecStop=/usr/local/bin/bitcoin-cli stop
Type=forking
User=bitcoin
Group=bitcoin
PIDFile=/home/bitcoin/.bitcoin/bitcoind.pid
Restart=on-failure

[Install]
WantedBy=multi-user.target

$ sudo systemctl daemon-reload
$ sudo systemctl enable bitcoind
$ sudo systemctl start bitcoind
$ journalctl -u bitcoind -f

5. Useful commands

Day-to-day checks live here in short form. The full operator library — sync, disk, peers, mempool, logs, restart — is on the commands page.

$ bitcoin-cli getblockchaininfo
$ bitcoin-cli getconnectioncount
$ bitcoin-cli getnetworkinfo
$ df -h ~/.bitcoin

6. Troubleshooting

Work top-down: is the process up, is disk free, are there peers, is IBD actually stuck? Prefer read-only bitcoin-cli checks from the commands library before changing config.

Stuck or painfully slow IBD

verificationprogress can sit still for a long time on USB disks, SD cards, or oversubscribed VPS CPU. Confirm blocks vs headers, peer count, and free space.

$ bitcoin-cli getblockchaininfo
$ bitcoin-cli getconnectioncount
# Raise dbcache only if you have spare RAM (see conf sample above)
# Move datadir to NVMe if you are still on SD/USB HDD

If headers advance but blocks crawl on NVMe with peers > 0, wait longer or raise dbcache. If both stall, fix network first. Deep dive: sync stuck. Hardware IO notes: hardware comparison.

Disk full during sync

Stop cleanly (bitcoin-cli stop or systemctl stop bitcoind). Do not delete random files under blocks/. Expand the volume, move the datadir, or enable prune in bitcoin.conf before restarting. Field guide: disk full & pruned. Trade-offs: pruned vs full. VPS disk math: VPS comparison.

Few or zero peers

Outbound internet must work. Corporate firewalls and some VPS images block unexpected egress. Inbound peers need port 8333 (or Tor). Low peer counts on Tor-only configs can be normal — see Tor and privacy.

$ bitcoin-cli getnetworkinfo
$ bitcoin-cli getconnectioncount
$ bitcoin-cli getpeerinfo | head -20

Wrong architecture binary

cannot execute binary file: Exec format error means you installed x86_64 on aarch64 (or the reverse). Pi 5 and most ARM boards need the aarch64 tarball from bitcoincore.org. Re-download, verify, reinstall.

systemd will not start

Check the unit user exists, datadir permissions, and journal output. A missing bitcoin user or root-owned ~/.bitcoin is a common footgun.

$ systemctl status bitcoind --no-pager
$ journalctl -u bitcoind -n 80 --no-pager
$ ls -la /home/bitcoin/.bitcoin

RPC connection refused (localhost by design)

Sample config keeps rpcallowip=127.0.0.1. Calls from another machine on your LAN will fail — that is intentional. Do not “fix” it by binding RPC to 0.0.0.0 or forwarding port 8332. See security basics.

7. Upgrading Bitcoin Core

New stable releases ship regularly. Stop safely before upgrading.

$ bitcoin-cli stop
# Download new release, verify, install
$ sudo install -m 0755 -o root -g root -t /usr/local/bin bitcoin-NEW/bin/*
$ sudo systemctl start bitcoind

FAQ