Building Zen

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.
• sccache (Download here) – A caching tool that speeds up rebuilds by storing compiled objects.
• Rust and Cargo (Download here) - Required to apply firefox patches.

Step 1: Getting Started & Clone the Project

First, let's get your system ready for building Zen.

After having everything set up, 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 --depth 10
cd desktop

• --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. The process may take some time, and there may be periods of time where it appears inactive — but rest assured, the commands are running in the background.

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.

Step 6: Run the Browser

After building the browser, you can start it using:

npm start

This command launches the browser, allowing you to see your changes in action.

Common Build Errors & Fixes

Q: "mach not found" error?

Install MozillaBuild, add it to your PATH, then restart your terminal.

Q: "7z" or "7-Zip" missing during build?

Download 7-Zip, add it to your PATH, then restart your terminal.

Q: "Unsupported Microsoft Visual Studio version" or build failing for similar reasons on Windows?

Ensure Visual Studio is installed with the "Desktop development with C++" workload and Windows 10/11 SDK.

Q: Build stuck or freezing?

Try running with fewer threads:

npm run build -- --jobs 2

Q: "Git submodule" errors after cloning?

Run:

git submodule update --init --recursive

Q: "npm run init" fails?

Manually bootstrap the project:

npm run bootstrap

Q: "zen.exe" not found after build?

Perform a clean rebuild:

npm run reset-ff && npm run init && npm run build