Inside Bitcoin

1# macOS Build Guide
2
3**Updated for MacOS [26](https://www.apple.com/os/macos/)**
4
5This guide describes how to build bitcoind, command-line utilities, and GUI on macOS.
6
7## Preparation
8
9The commands in this guide should be executed in a Terminal application.
10macOS comes with a built-in Terminal located in:
11
12```bash
13/Applications/Utilities/Terminal.app
14```
15
16### 1. Xcode Command Line Tools
17
18The Xcode Command Line Tools are a collection of build tools for macOS.
19Version 16.2 (or higher) of these tools must be
20[installed](https://developer.apple.com/documentation/xcode/installing-the-command-line-tools)
21in order to build Bitcoin Core from source.
22
23To install, run the following command from your terminal:
24
25``` bash
26xcode-select --install
27```
28
29Upon running the command, you should see a popup appear.
30Click on `Install` to continue the installation process.
31
32### 2. Homebrew Package Manager
33
34Homebrew is a package manager for macOS that allows one to install packages from the command line easily.
35While several package managers are available for macOS, this guide will focus on Homebrew as it is the most popular.
36Since the examples in this guide which walk through the installation of a package will use Homebrew, it is recommended that you install it to follow along.
37Otherwise, you can adapt the commands to your package manager of choice.
38
39To install the Homebrew package manager, see: https://brew.sh
40
41Note: If you run into issues while installing Homebrew or pulling packages, refer to [Homebrew's troubleshooting page](https://docs.brew.sh/Troubleshooting).
42
43### 3. Install Required Dependencies
44
45The first step is to download the required dependencies.
46These dependencies represent the packages required to get a barebones installation up and running.
47
48See [dependencies.md](dependencies.md) for a complete overview.
49
50To install, run the following from your terminal:
51
52``` bash
53brew install cmake boost capnp
54```
55
56#### Wallet Dependencies
57
58If you do not need wallet functionality, you can use `-DENABLE_WALLET=OFF` in
59the `cmake -B` step below.
60
61SQLite is required, but since macOS ships with a useable `sqlite` package, you don't need to
62install anything.
63
64#### IPC Dependencies
65
66If you do not need IPC functionality (see [multiprocess.md](multiprocess.md))
67you can omit `capnp` and use `-DENABLE_IPC=OFF` in the `cmake -B` step below.
68
69### 4. Clone Bitcoin repository
70
71`git` should already be installed by default on your system.
72Now that all the required dependencies are installed, let's clone the Bitcoin Core repository to a directory.
73All build scripts and commands will run from this directory.
74
75``` bash
76git clone https://github.com/bitcoin/bitcoin.git
77```
78
79### 5. Install Optional Dependencies
80
81#### GUI Dependencies
82
83###### Qt
84
85Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install
86Qt, libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI.
87
88``` bash
89brew install qt@6
90```
91
92Note: Building with Qt binaries downloaded from the Qt website is not officially supported.
93See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714).
94
95###### libqrencode
96
97The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run:
98
99``` bash
100brew install qrencode
101```
102
103Otherwise, if you don't need QR encoding support, you can pass `-DWITH_QRENCODE=OFF` to disable this feature.
104
105---
106
107#### ZMQ Dependencies
108
109Bitcoin Core can provide notifications via ZeroMQ. To compile ZMQ support, install the following dependency and pass `-DWITH_ZMQ=ON` when configuring.
110Skip if you do not need ZMQ functionality.
111
112``` bash
113brew install zeromq pkgconf
114```
115
116Check out the [further configuration](#further-configuration) section for more information.
117
118For more information on ZMQ, see: [zmq.md](zmq.md)
119
120---
121
122#### Test Suite Dependencies
123
124There is an included test suite that is useful for testing code changes when developing.
125To run the test suite (recommended), you will need to have Python 3 installed:
126
127``` bash
128brew install python
129```
130
131---
132
133#### Deploy Dependencies
134
135You can [deploy](#3-deploy-optional) a `.zip` containing the Bitcoin Core application.
136It is required that you have `python` and `zip` installed.
137
138## Building Bitcoin Core
139
140### 1. Configuration
141
142There are many ways to configure Bitcoin Core, here are a few common examples:
143
144##### Wallet and GUI:
145
146This enables the GUI.
147If `sqlite` or `qt` are not installed, this will throw an error.
148
149``` bash
150cmake -B build -DBUILD_GUI=ON
151```
152
153##### No Wallet or GUI
154
155``` bash
156cmake -B build -DENABLE_WALLET=OFF
157```
158
159##### Further Configuration
160
161You may want to dig deeper into the configuration options to achieve your desired behavior.
162Examine the output of the following command for a full list of configuration options:
163
164``` bash
165cmake -B build -LH
166```
167
168### 2. Compile
169
170After configuration, you are ready to compile.
171Run the following in your terminal to compile Bitcoin Core:
172
173``` bash
174cmake --build build     # Append "-j N" here for N parallel jobs.
175ctest --test-dir build  # Append "-j N" for N parallel tests.
176```
177
178### 3. Deploy (optional)
179
180You can also create a `.zip` containing the `.app` bundle by running the following command:
181
182``` bash
183cmake --build build --target deploy
184```
185
186## Running Bitcoin Core
187
188Bitcoin Core should now be available at `./build/bin/bitcoind`.
189If you compiled support for the GUI, it should be available at `./build/bin/bitcoin-qt`.
190
191There is also a multifunction command line interface at `./build/bin/bitcoin`
192supporting subcommands like `bitcoin node`, `bitcoin gui`, `bitcoin rpc`, and
193others that can be listed with `bitcoin help`.
194
195The first time you run `bitcoind` or `bitcoin-qt`, it will start downloading the blockchain.
196This process could take many hours, or even days on slower than average systems.
197
198By default, blockchain and wallet data files will be stored in:
199
200``` bash
201/Users/${USER}/Library/Application Support/Bitcoin/
202```
203
204Before running, you may create an empty configuration file:
205
206```shell
207mkdir -p "/Users/${USER}/Library/Application Support/Bitcoin"
208
209touch "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf"
210
211chmod 600 "/Users/${USER}/Library/Application Support/Bitcoin/bitcoin.conf"
212```
213
214You can monitor the download process by looking at the debug.log file:
215
216```shell
217tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log
218```
219
220## Other commands:
221
222```shell
223./build/bin/bitcoind -daemon      # Starts the bitcoin daemon.
224./build/bin/bitcoin-cli --help    # Outputs a list of command-line options.
225./build/bin/bitcoin-cli help      # Outputs a list of RPC commands when the daemon is running.
226./build/bin/bitcoin-qt -server # Starts the bitcoin-qt server mode, allows bitcoin-cli control
227```
228