Building from source on macOS

This guide is for users intending to develop CockroachDB.

To USE CockroachDB consult these docs instead: and

This is a guide for getting productive to code on CockroachDB on OS X / macOS. This assumes a blank machine/nothing is installed.

  1. Install homebrew.

  2. Install XCode Command Line Tools, using

    1 xcode-select --install
  3. Install XCode from the Mac App store and open it at least once so the developer tools can initialize.

  4. Install the following brew packages:

    1 2 3 brew install git brew install --cask docker brew install git autoconf cmake node@16 yarn go ccache bazelisk make

    OS X ships with a git, but it's old. Once you install git via brew, relaunch your terminal to make sure your git version is up to date. You can confirm this by comparing the output of

    1 which git

    to the output of

    1 echo $(brew --prefix)/bin/git

    If they match, you're using brew's git! You also need to use brew’s make. brew installs make in a special directory, so you need to update your PATH to look for it. On MacOS, you will need to add the following line to either ~/.zshrc, ~/.bashrc, or ~/.bash_profile depending on which shell you use.

    1 export PATH="/usr/local/opt/make/libexec/gnubin:$PATH"

    Restart your shell, and confirm this directory is being used.

    1 which make
  5. Install Go. Options include:

    • Official installer via clicking (don't do this)

    • Official installer via brew install --cask go (it's ok)

    • homebrew via brew install go (it's ok)

    • from source (you already know what you're doing, right?)

  6. Clone the repo using git and navigate into it

    1 2 3 4 mkdir -p $(go env GOPATH)/src/ cd $(go env GOPATH)/src/ git clone cd cockroach
  7. Add your fork as a remote (assuming you forked cockroach on GitHub)
    git remote add yourgithubusername

  8. Start the docker app in the usual fashion.

  9. You should be good to run make! This should take a long time, as it pulls various go dependencies. Afterwards, you can start a cockroach instance using ./cockroach, e.g. ./cockroach demo. You can also use make buildshort, which will build the same Cockroach binary without the DB Console, which is faster to compile.