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:

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

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


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.

3. Build and Run

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

cd mozilla-unified
hg up -C central
./mach build

🎉 Congratulations! You’ve built your own home-grown Firefox! You should see the following message in your terminal after a successful build:

Your build was successful!
To take your build for a test drive, run: |mach run|
For more information on what to do now, see

You can now use the ./mach run command to run your locally built Firefox!

If your build fails, please reference the steps in the Troubleshooting section.


Code signing your Mac build is not required for local testing and is rarely needed for development. The way Firefox is signed does impact functionality such as passkey support so it is required in some cases. Generating a build as close to a production build as possible requires code signing. See Signing Local macOS Builds for more information.

Running outside the development environment

To test your changes on another macOS system (or to keep that particular Firefox around after new builds), you can’t just use the generated application bundle (obj-*/dist/Nightly[Debug].app), since it contains symbolic links to other built libraries. Instead, build a distributable disk image with:

./mach package

Copy the resulting .dmg file from obj-*/dist/ to the target system, then double-click it as usual to find an .app bundle containing all dependencies.

On Apple Silicon Macs, you will need to sign the build for this to work using Signing Local macOS Builds.

Once the build has been copied to the target system, open it with right-click->Open. The build will not launch by default because it is not notarized. In addition to code signing, notarization is required on macOS 10.15+ for a downloaded app to be launchable by double clicking the app in Finder.

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.


Build errors

If you encounter a build error when trying to setup your development environment, please follow these steps:
  1. Copy the entire build error to your clipboard

  2. Paste this error to in the text area and change the “Expire in one hour” option to “Expire in one week”. Note: it won’t take a week to get help but it’s better to have the snippet be around for a bit longer than expected.

  3. Go to the introduction channel and ask for help with your build error. Make sure to post the link to the snippet you created!