Building Firefox On Linux

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: A 64-bit installation of Linux. It is advisable to ensure that your system is fully up-to-date.


Some Linux distros are better-supported than others. Mozilla maintains bootstrapping code for Ubuntu, but others are managed by the community (thanks!). The more esoteric the distro you’re using, the more likely that you’ll need to solve unexpected problems.

1. System preparation

1.1 Install Python

To build Firefox, it’s necessary to have a Python of version 3.6 or later installed. Python 2 is no longer required to build Firefox, although it is still required for running some kinds of tests. Additionally, you will probably need Python development files as well to install some pip packages.

You should be able to install Python using your system package manager:

  • For Debian-based Linux (such as Ubuntu): sudo apt-get install python3 python3-dev

  • For Fedora Linux: sudo dnf install python3 python3-devel

If you need a version of Python that your package manager doesn’t have (e.g.: the provided Python 3 is too old, or you want Python 2 but it’s not available), then you can use pyenv, assuming that your system is supported.

1.2 Install Mercurial

Mozilla’s source code is hosted in Mercurial repositories. You will need Mercurial to download and update the code.

Note that if you’d prefer to use the version of Mercurial that is packaged by your distro, you can skip this section. However, keep in mind that distro-packaged Mercurial may be outdated, and therefore slower and less supported.

python3 -m pip install --user mercurial

You can test that Mercurial is installed by running:

hg version


If your shell is showing command not found: hg, then Python’s packages aren’t being found in the $PATH. You can resolve this by doing the following and restarting your shell:

# If you're using zsh
echo "export PATH=\"$(python3 -m site --user-base)/bin:$PATH\"" >> ~/.zshenv

# If you're using bash
echo "export PATH=\"$(python3 -m site --user-base)/bin:$PATH\"" >> ~/.bashrc

# If you're using a different shell, follow its documentation to see
# how to configure your PATH. Ensure that `$(python3 -m site --user-base)/bin`
# is prepended.

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 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

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.


Using a non-native file system (NTFS, network drive, etc)

In our experience building Firefox in these hybrid or otherwise complex environments always ends in unexpected, often silent and always hard-to-diagnose failure. Building Firefox in that environment is far more likely to reveal the flaws and shortcomings of those systems than it is to produce a running web browser.