docs: Split Mac install instructions
What changed, and why it matters
This commit only updates the macOS installation instructions in the documentation. It splits the guide into separate Apple Silicon and Intel Mac sections and adds tips for avoiding the wrong Homebrew version. There are no code changes and no security issue is being fixed or introduced.
No security action needed. Treat as a routine documentation improvement.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff modifies doc/getting-started/getting-started/installation.md only. It reorganizes macOS build instructions, adds architecture detection (arch), Homebrew path checks (which brew / which pkg-config), environment variable guidance for /opt/homebrew vs /usr/local, and a duplicated Intel-specific section. No source code, build scripts, or cryptographic logic is changed.
Changed components
doc/getting-started/getting-started/installation.mdInspect captured patch +110 / −12
diff --git a/doc/getting-started/getting-started/installation.md b/doc/getting-started/getting-started/installation.md
index dfc064f0..59a19c57 100644
--- a/doc/getting-started/getting-started/installation.md
+++ b/doc/getting-started/getting-started/installation.md
@@ -324,30 +324,47 @@ poetry install
make
```
-## To Build on macOS
+## To Build on macOS Apple Silicon
-Assuming you have Xcode and Homebrew installed. Install dependencies:
+Assuming you have Xcode and Homebrew installed.
+First confirm which architecture of Mac you are running
```shell
-brew install autoconf automake libtool python3 gnu-sed gettext libsodium protobuf lowdown
-export PATH="/usr/local/opt:$PATH"
+arch
```
+If you see this result: `arm64`
+Continue with these instructions. If you see any other result switch to Build on macOS Intel instructions.
-If you need SQLite (or get a SQLite mismatch build error):
-
+Confirm you are using Apple Silicon Homebrew
```shell
-brew install sqlite
-export LDFLAGS="-L/usr/local/opt/sqlite/lib"
-export CPPFLAGS="-I/usr/local/opt/sqlite/include"
+which brew
+which pkg-config
```
+If you see this result:
+```
+/opt/homebrew/bin/brew
+/opt/homebrew/bin/pkg-config
+```
+You are using Apple Silicon Homebrew and can continue with the instructions, skip to "Install dependencies"
-Some library paths are different when using `homebrew` on Macs with Apple silicon, therefore the following two variables need to be set for Macs with Apple silicon:
+If you see this in the result: `/usr/local/bin/brew`
+You are using brew in Intel compatibility mode. The simplest solution is to remove brew entirely, reinstall it, and start these instructions over.
+
+Install dependencies:
```shell
+brew install autoconf automake libtool python3 gnu-sed gettext libsodium protobuf lowdown pkgconf openssl
+export PATH="/opt/homebrew/opt/:$PATH"
export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib
```
+If you need SQLite (or get a SQLite mismatch build error):
+
+```shell
+brew install sqlite
+```
+
Install uv for Python dependency management:
```shell
@@ -385,6 +402,11 @@ Build lightning:
```shell
uv sync --all-extras --all-groups --frozen
./configure
+```
+
+If you see `/usr/local` in the log, an Intel compatability dependency has been picked up. The simplest solution is to remove brew entirely, reinstall it, and start these instructions over.
+
+```shell
uv run make
```
@@ -406,10 +428,86 @@ To install the built binaries into your system, you'll need to run `make install
make install
```
-On a Mac with Apple silicon, you may need to use this command instead:
+You may need to use this command instead. Confirm the exported PATH, CPATH, and LIBRARY_PATH environment varaibles set earlier are still present.
+```shell
+sudo make install
+```
+
+## To Build on macOS Intel
+
+Assuming you have Xcode and Homebrew installed.
+
+Install dependencies:
+
+```shell
+brew install autoconf automake libtool python3 gnu-sed gettext libsodium protobuf lowdown pkgconf openssl
+export PATH="/usr/local/opt/:$PATH"
+export CPATH=/usr/local/include
+export LIBRARY_PATH=/usr/local/lib
+```
+
+If you need SQLite (or get a SQLite mismatch build error):
+
+```shell
+brew install sqlite
+```
+
+Install uv for Python dependency management:
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+After installing uv, restart your shell or run `source ~/.zshrc` to ensure `uv` is in your PATH.
+
+If you don't have bitcoind installed locally you'll need to install that as well:
+
+```shell
+brew install boost cmake pkg-config libevent
+git clone https://github.com/bitcoin/bitcoin
+cd bitcoin
+cmake -B build
+cmake --build build --target bitcoind bitcoin-cli
+cmake --install build --component bitcoind && cmake --install build --component bitcoin-cli
+```
+
+Clone lightning:
+
+```shell
+git clone https://github.com/ElementsProject/lightning.git
+cd lightning
+```
+
+Checkout a release tag:
+
+```shell
+git checkout v24.05
+```
+
+Build lightning:
+
+```shell
+uv sync --all-extras --all-groups --frozen
+./configure
+uv run make
+```
+
+Running lightning:
+
+> 📘
+>
+> Edit your `~/Library/Application\ Support/Bitcoin/bitcoin.conf`to include `rpcuser=<foo>` and `rpcpassword=<bar>` first, you may also need to include `testnet=1`.
```shell
-sudo PATH="/usr/local/opt:$PATH" LIBRARY_PATH=/opt/homebrew/lib CPATH=/opt/homebrew/include make install
+bitcoind &
+./lightningd/lightningd &
+./cli/lightning-cli help
+```
+
+To install the built binaries into your system, you'll need to run `make install`:
+
+```shell
+make install
```
## To Build on Arch Linux
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.