Building Zen Browser

We've taken the time to make building Zen Browser as easy as possible, independent of your operating system or technical knowledge.

Basic Requirements

The following resources are essential for a successful build. Without them, you will encounter unnecessary build failures:

Disk Space: Keep 30GB of free space on the disk (the build process is resource-intensive).
Git (Download here) – Required for version control and managing source code.
Python 3 (Download here) – Needed for running build scripts and automation tools.
Node.js 21+ (Download here) – Required for managing dependencies and running JavaScript-based tools.
MozillaBuild (Download here) – Required for mach and Gecko compilation.
7-Zip (Download here) – Used to extract Firefox source archives.
sccache (Download here) – A caching tool that speeds up rebuilds by storing compiled objects.

If you're using Windows, ensure that all the basic software requirements are added to the PATH variable.

We cannot provide support if a build fails. Please understand this before proceeding with the following steps.

Step 1: Clone the Project

First, you need to clone the Zen Browser repository to your local machine. This will create a local copy of the project that you can work on.

git clone https://github.com/zen-browser/desktop.git --recurse-submodules --depth 10
cd desktop

--recurse-submodules: This flag ensures that all submodules are cloned along with the main project. Zen Browser relies on several submodules, so this step is essential.
--depth 10: This makes sure you dont download the entire git history, it would take a long time otherwise due to that we used to store compiled binaries on the repository.

Step 2: Install Dependencies

Once you have cloned the project, navigate to the project directory and install the necessary dependencies using npm:

npm i

This command will install all the packages listed in the package.json file, which are required for building and running Zen Browser.

Step 3: Download and Bootstrap the Browser

To set up the browser, you need to download additional files and prepare the environment:

npm run init

This command handles all the necessary bootstrapping tasks, such as setting up configuration files and downloading essential resources.

Step 4: Update Language Packs

Before building the browser, it’s recommended to update the American English language packs to ensure that all localization files are up-to-date:

python3 ./scripts/update_en_US_packs.py

This script updates the "en-US" localization files, which are necessary for proper language support in Zen Browser. Running this step ensures that your build includes the latest translations and language resources.

Step 5: Build the Browser

Now that everything is set up, you can build the browser:

npm run build

This command compiles the source code and creates the necessary files for running Zen Browser.

If your changes are only in JavaScript, you can run the following command after completing the first build for faster rebuilds:
npm run build:ui
This skips unnecessary compilation steps and only rebuilds the UI components.

For changes in other languages or core functionality, you should always run the full build using npm run build after every code change.