Building Firefox On macOS

This document will help you get set up to build Firefox on your own computer. Getting set up can take a while - we need to download a lot of bytes! Even on a fast connection, this can take ten to fifteen minutes of work, spread out over an hour or two.


  • Memory: 4GB RAM minimum, 8GB+ recommended.

  • Disk Space: At least 30GB of free disk space.

  • Operating System: macOS - most recent or prior release. It is advisable to upgrade to the latest “point” release. See Supported Build Hosts for more information.

1. System preparation

1.1. Install Brew

Mozilla’s source tree requires a number of third-party tools. You will need to install Homebrew so that we can automatically fetch the tools we need.

1.2. Install Xcode

Install Xcode from the App Store. Once done, finalize the installation in your terminal:

sudo xcode-select --switch /Applications/
sudo xcodebuild -license

1.3 Install Mercurial

Mozilla’s source code is hosted in Mercurial repositories. You will need Mercurial to download and update the code. Additionally, we’ll put user-wide python package installations on the $PATH, so that both hg and moz-phab will be easily accessible:

NOTE Pay special attention to the ==6.1.4, as Mercurial >=6.2 is incompatible with several plugins

echo "export PATH=\"$(python3 -m site --user-base)/bin:$PATH\"" >> ~/.zshenv
python3 -m pip install --user mercurial==6.1.4

Now, restart your shell so that the PATH change took effect. You can test that Mercurial is installed by running:

hg version


If you’re using a shell other than zsh, you’ll need to manually add Python’s bin directory to your PATH, as your shell probably won’t pick up our changes in ~/.zshenv.

2. Bootstrap a copy of the Firefox source code

Now that your system is ready, we can download the source code and have Firefox automatically download the other dependencies it needs. The below command will download a lot of data (years of Firefox history!) then guide you through the interactive setup process.

curl -O


In general, the Firefox workflow works best with Mercurial. However, if you’d prefer to use git, you can grab the source code in “git” form by running the bootstrap script with the vcs parameter:

python3 --vcs=git

This uses Git Cinnabar under the hood.

Choosing a build type

If you aren’t modifying the Firefox backend, then select one of the Artifact Mode options. If you are building Firefox for Android, you should also see the GeckoView Contributor Guide.


After finishing the bootstrap process, can be removed.


3. Build

Now that your system is bootstrapped, you should be able to build!

cd mozilla-unified
./mach build
./mach run

🎉 Congratulations! You’ve built your own home-grown Firefox!

Now the fun starts

Time to start hacking! You should join us on Matrix, say hello in the Introduction channel, and find a bug to start working on. See the Firefox Contributors’ Quick Reference to learn how to test your changes, send patches to Mozilla, update your source code locally, and more.


macOS SDK is unsupported

If the SDK included with your Xcode installation is not supported by Firefox, you’ll need to manually install one that is compatible. We’re currently using the 11 SDK on our build servers, so that’s the one that you should install:

  1. Go to the More Downloads for Apple Developers page and download Xcode 12.5.1.

  2. Once downloaded, extract Xcode_12.5.1.xip.

  3. In your terminal, copy the SDK from the installer:

mkdir -p ~/.mozbuild/macos-sdk
# This assumes that Xcode is in your "Downloads" folder
cp -aH ~/Downloads/ ~/.mozbuild/macos-sdk/
  1. Finally, inform the Firefox build about this SDK by creating (or editing) a file called mozconfig file in the Firefox source code directory. Add the following line:

ac_add_options --with-macos-sdk=$HOME/.mozbuild/macos-sdk/MacOSX11.3.sdk
  1. Now, you should be able to successfully run ./mach build.

“FileNotFoundError” with some stuff about _virtualenvs and site-packages

You likely have Python 3.10 installed (Brew or XCode may have done this – We’re not sure how it happens). There is a bug in virtualenv that prevents us from even setting up the virtual environment.

Uninstall it with the following:

brew unlink python@3.10

If you need Python 3.10, you can re-link it after the fact with

brew link python@3.10