Skip to content
Get packs

Guide · Open source

How to use Bitcoin Core: clone, build and run the node

Updated · written with AI from the project's own documentation and checked against our catalogue data

Bitcoin Core is the reference software that connects to the Bitcoin peer-to-peer network and downloads and fully validates every block and transaction, so you do not have to rely on a third party's record of the ledger. This guide explains what the bitcoin/bitcoin repository contains, how to clone it, where the build and test instructions live, and when a ready-made download is the better choice. After reading it you will know which path fits your goal and what to do next.

Bitcoin Corebitcoin/bitcoin · ★ 90.6k · MIT

Quick start

  1. 1Decide which version you need. If you only want to use Bitcoin, download the prebuilt binary from bitcoincore.org. Clone the source only if you want to build, test or review code.
  2. 2Clone the repository. Run git clone https://github.com/bitcoin/bitcoin in a terminal to get the source tree.
  3. 3Open the build instructions. Find the doc/build-*.md file that matches your operating system and follow it, since the README does not give build steps itself.
  4. 4Build the software. Follow the steps in your chosen build document, using a separate build directory named build as the tests assume.
  5. 5Run the tests. Run ctest for unit tests and build/test/functional/test_runner.py for the Python functional tests, if the test dependencies are installed.
  6. 6Read the contribution guide. Before changing code, read CONTRIBUTING.md and doc/developer-notes.md.

What is Bitcoin Core and who is it for?

Bitcoin Core connects to the Bitcoin peer-to-peer network to download and fully validate blocks and transactions. It also includes a wallet and a graphical user interface, which can be optionally built.

This is a good fit if you want to verify Bitcoin transactions yourself, if you develop or test Bitcoin protocol software, or if you can run software on a machine that stays online. It is not the fastest route if you only want to send or receive bitcoin.

  • Verify transactions yourself instead of trusting a third party
  • Develop, review or test Bitcoin protocol software
  • Operate a node on a machine that stays online

Should you clone the source or download a binary?

This repository is the development ('integration/staging') tree, not the ready-to-use download. The README states that an immediately usable, binary version is available at bitcoincore.org/en/download. If you simply want to run Bitcoin Core, start there.

The master branch is regularly built and tested but is not guaranteed to be completely stable. Stable releases are marked with tags created from release branches.

  • Want to run the software quickly: use the prebuilt download at https://bitcoincore.org/en/download
  • Want to build, test or review code: clone this repository

Clone the repository

The README lists one install command: clone the repository from GitHub. The README does not list other prerequisites, so check the build documents before you start.

git clone https://github.com/bitcoin/bitcoin

Build from source using the build documents

The README does not contain build steps itself. It points to separate instructions in the doc folder, named doc/build-*.md, which cover the build for each platform. The README also notes that the build process is not beginner-friendly, so follow the document that matches your operating system closely.

Bitcoin Core also has a doc folder with more information about the software, and doc/developer-notes.md holds hints for developers.

  • Open the doc/ folder in the cloned repository
  • Choose the doc/build-*.md file for your operating system
  • Read doc/developer-notes.md if you plan to change code

Run the unit and functional tests

Developers are encouraged to write unit tests for new code. Unit tests can be compiled and run with ctest, assuming they were not disabled when the build system was generated. More detail is in src/test/README.md.

Regression and integration tests are written in Python in the test folder. They run with the test runner, if the test dependencies are installed, and assume build is your build directory.

  • Unit tests: run ctest, see src/test/README.md
  • Functional tests: build/test/functional/test_runner.py (assumes your build directory is build)
ctest

Contribute and help test pull requests

Read CONTRIBUTING.md for the contribution workflow. Code review and testing are the project's bottleneck, so the README asks contributors to help test other people's pull requests. Changes should be tested by someone other than the developer who wrote them, and a test plan in the pull request description helps when testing is not straightforward.

Translations are not submitted as GitHub pull requests. They go through Bitcoin Core's Transifex page, because the next pull from Transifex would overwrite direct changes.

  • Read CONTRIBUTING.md before opening a pull request
  • Test other people's pull requests when you can
  • Submit translations on Transifex, not as GitHub pull requests

What people use it for

  • Verifying Bitcoin transactions on your own node instead of trusting a third party
  • Developing or testing changes to Bitcoin protocol software
  • Reviewing and testing other people's pull requests
  • Running a node on a machine that stays online

Frequently asked questions

Is Bitcoin Core free to use?

Yes, Bitcoin Core is released under the MIT license. The COPYING file in the repository has the full terms. The license governs the software, not any bitcoin you may hold.

Can I install Bitcoin Core without building it from source?

Yes. The README says an immediately usable binary version is available at bitcoincore.org/en/download. Building from this repository is only needed if you want to develop, test or review the code.

What are the system requirements for Bitcoin Core?

The README does not state storage, memory or bandwidth requirements. It notes that a full node downloads and validates the whole chain, so check the official download page for current details before you install.

Why does the README not include build steps?

The README points to separate build documents, named doc/build-*.md, for each platform. It lists only the git clone command, so you need to read the matching build document to compile the software.

Is the master branch safe to run?

The README says master is regularly built and tested but is not guaranteed to be completely stable. Stable releases are marked by tags, so use a tagged release or the official binary for everyday use.

What are the alternatives to Bitcoin Core?

Comparable projects listed for this item include btcd, Bitcoin Knots, libbitcoin and BTCPay Server. Each has a different focus, so compare them against what you need before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Bitcoin Core suits people who want to verify transactions themselves, developers working on protocol software, and anyone who can run a node on an always-on machine. If you just want to send or receive bitcoin, or you lack spare disk space and bandwidth, use the prebuilt download or a different tool instead.

Install options & downloads