diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dae893ce2..773c27e37 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -36,15 +36,25 @@ Want to take on an issue? Leave a comment and a maintainer may assign it to you
1. Install
go,
docker, and
NodeJS. Note that a NodeJS version of at least `24` is required.
-2. Install [ctags](https://github.com/universal-ctags/ctags) (required by zoekt)
+2. Install [universal-ctags](https://github.com/universal-ctags/ctags) v6.1.0 (required by zoekt). Version 6.1.0 is required — newer versions have a known incompatibility with zoekt.
+
+ **macOS:** Run the provided install script:
```sh
- // macOS:
- brew install universal-ctags
+ ./install-ctags-macos.sh
+ ```
- // Linux:
- snap install universal-ctags
+ **Linux and other platforms:** Build from source:
+ ```sh
+ curl https://codeload.github.com/universal-ctags/ctags/tar.gz/v6.1.0 | tar xz -C /tmp
+ cd /tmp/ctags-6.1.0
+ ./autogen.sh
+ ./configure --program-prefix=universal- --enable-json
+ make -j$(nproc)
+ sudo make install
```
+ After installing, set `CTAGS_COMMAND` in your `.env.development.local` to the path of the installed binary (e.g. `/usr/local/bin/universal-ctags`).
+
3. Install corepack:
```sh
npm install -g corepack
diff --git a/install-ctags-macos.sh b/install-ctags-macos.sh
new file mode 100755
index 000000000..e856ece51
--- /dev/null
+++ b/install-ctags-macos.sh
@@ -0,0 +1,38 @@
+#!/bin/sh
+
+# This script installs universal-ctags v6.1.0 on macOS.
+# This version is pinned to match the version used in the Sourcebot Docker image.
+# See vendor/zoekt/install-ctags-alpine.sh for the Alpine equivalent.
+
+CTAGS_VERSION=v6.1.0
+CTAGS_ARCHIVE_TOP_LEVEL_DIR=ctags-6.1.0
+INSTALL_DIR=/usr/local/bin
+
+cleanup() {
+ cd /
+ rm -rf /tmp/ctags-$CTAGS_VERSION
+}
+
+trap cleanup EXIT
+
+set -eux
+
+# Ensure required build tools are available
+if ! command -v brew >/dev/null 2>&1; then
+ echo "Homebrew is required to install build dependencies. See https://brew.sh."
+ exit 1
+fi
+
+brew install autoconf automake pkg-config jansson
+
+curl --retry 5 "https://codeload.github.com/universal-ctags/ctags/tar.gz/$CTAGS_VERSION" | tar xz -C /tmp
+cd /tmp/$CTAGS_ARCHIVE_TOP_LEVEL_DIR
+./autogen.sh
+./configure --program-prefix=universal- --enable-json
+make -j"$(sysctl -n hw.ncpu)"
+sudo make install
+
+echo ""
+echo "universal-ctags installed to $INSTALL_DIR/universal-ctags"
+echo "Add the following to your .env.development.local:"
+echo " CTAGS_COMMAND=$INSTALL_DIR/universal-ctags"