# Brave Sync Process Explained: How to Use npm run sync Commands

> Understand the Brave sync process and learn how to use npm run sync commands to fetch Chromium revisions, apply patches, and prepare the codebase for compilation. Master your build environment.

- Repository: [Brave Software/brave-browser](https://github.com/brave/brave-browser)
- Tags: internals
- Published: 2026-02-16

---

**The Brave sync process is a build-time routine that fetches the latest Chromium and brave-core revisions, applies Brave-specific patches, updates the DEPS file, and runs post-fetch hooks to prepare the multi-repository codebase for compilation.**

The `brave/brave-browser` repository orchestrates a complex build system that depends on several large sub-projects, including Chromium and brave-core. Instead of manually managing these dependencies, developers use the Brave sync process through `npm run sync` commands to automatically fetch code, apply patches, and synchronize versions across the entire tree.

## What Is the Brave Sync Process?

Brave Browser is constructed from multiple independent repositories. The sync process is a Node.js-based script defined in the repository’s [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json) that automates four critical build preparation steps:

1. **Fetches the latest revisions** of Chromium, brave-core, and helper repositories (or specific refs you designate).
2. **Applies Brave-specific patches** stored in the repository to adapt upstream code.
3. **Updates the `src/brave/DEPS` file** used by Chromium’s `gclient` tool to ensure dependency versions remain consistent.
4. **Runs post-fetch hooks**, such as `npm install` inside child repositories, ensuring the code is ready for compilation.

According to the repository's [`README.md`](https://github.com/brave/brave-browser/blob/main/README.md), `npm run sync` "updates sub-projects (chromium, brave-core) to latest commit of a git ref … Apply patches … Update gclient DEPS dependencies … Run hooks"【/cache/repos/github.com/brave/brave-browser/master/README.md#L21-L27】.

## How to Use npm run sync Commands

The `npm run sync` command serves as the primary interface for the Brave sync process. Flags are passed after a double-dash (`--`) to forward them to the underlying script.

### Core Sync Flags and Options

| Flag | Function | When to Use |
|------|----------|-------------|
| **(no flags)** | Updates Chromium only if its version changed, re-applies changed patches, and updates child dependencies only if a project changed. | Daily development to keep the tree current without forcing full rebuilds. |
| `--force` | Forces both Chromium and brave-core to the latest remote commit and re-applies **all** patches; forces all child dependencies. | When the local tree is corrupted or you need a clean reset to the tip. |
| `--init` | Forces Chromium and brave-core to the versions pinned in [`brave-core/package.json`](https://github.com/brave/brave-browser/blob/main/brave-core/package.json) and updates every dependent repo. | Fresh checkouts or after switching major release branches. |
| `--sync_chromium (true\|false)` | Explicitly forces or skips Chromium version updates. | Skip a large Chromium bump you're not ready to compile. |
| `-D, --delete_unused_deps` | Deletes sub-projects removed since the last sync (mirrors `gclient sync -D`). | Clean up after DEPS changes drop dependencies. |
| `--create` | Creates a new sync branch (used by internal tooling). | Advanced workflows for custom branch handling. |
| `brave_core_ref` (positional) | Checks out the specified brave-core ref before syncing the rest of the tree. | Pinning specific brave-core versions for reproducible builds. |

### Command Syntax Examples

Pass flags after the double-dash to ensure they reach the sync script:

```bash

# Basic update – minimal work, safe for daily use

npm run sync

# Force reset everything to latest remote

npm run sync -- --force

# Initialize fresh checkout to pinned versions

npm run sync -- --init

# Skip Chromium update (useful for avoiding long rebuilds)

npm run sync -- --sync_chromium=false

# Clean up deleted dependencies

npm run sync -- -D

```

## Where Sync Logic Lives in the Repository

The Brave sync process relies on several key files across the repository:

- **[`README.md`](https://github.com/brave/brave-browser/blob/main/README.md)** – Documents the high-level sync workflow, available flags, and usage examples.
- **`src/brave/DEPS`** – The Chromium-style DEPS file listing exact Git repositories and revisions for Chromium, brave-core, and other dependencies. The sync script reads this to determine what to fetch.
- **[`package.json`](https://github.com/brave/brave-browser/blob/main/package.json)** (root) – Declares the `sync` npm script that serves as the entry point for `npm run sync`.
- **`gclient`** (external tool) – Invoked by the sync script to materialize the dependencies specified in `DEPS`.
- **Patch files** (`*.patch` throughout the repo) – Applied after fetching to inject Brave-specific modifications into upstream code.

According to the repository documentation, the build system "fetches and syncs code from the projects defined in [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json) and `src/brave/DEPS`"【/cache/repos/github.com/brave/brave-browser/master/README.md#L5-L6】.

## Common Brave Sync Scenarios

| Situation | Command |
|-----------|---------|
| **Create a new feature branch** | ```bash<br>cd src/brave<br>git checkout -b my-feature<br>npm run sync<br>``` |
| **Update current branch to latest remote** | ```bash<br>git pull<br>npm run sync<br>``` |
| **Reset to latest brave-core master** | ```bash<br>git checkout master<br>git pull<br>npm run sync -- --init<br>``` |
| **Only patches changed, no Chromium bump** | ```bash<br>npm run sync<br>``` |
| **Force clean state after broken sync** | ```bash<br>npm run sync -- --force<br>``` |
| **Sync to specific brave-core tag** | ```bash<br>npm run sync v1.2.3<br>``` |

## Summary

- The **Brave sync process** is a build-time automation that fetches Chromium and brave-core revisions, applies Brave-specific patches, updates `src/brave/DEPS`, and runs post-fetch hooks.
- Use **`npm run sync`** as the primary command, passing flags after `--` to control behavior.
- Key flags include **`--force`** (full reset), **`--init`** (fresh checkout to pinned versions), **`--sync_chromium=false`** (skip Chromium updates), and **`-D`** (delete unused dependencies).
- The sync logic is defined in the repository's **[`README.md`](https://github.com/brave/brave-browser/blob/main/README.md)**, orchestrated through **[`package.json`](https://github.com/brave/brave-browser/blob/main/package.json)**, and executes against the **`src/brave/DEPS`** file using Chromium's `gclient` tooling.

## Frequently Asked Questions

### What does npm run sync actually do behind the scenes?

The command executes a Node.js script that calls `gclient sync` to materialize dependencies listed in `src/brave/DEPS`, applies all `*.patch` files found in the repository to modify upstream code, and executes post-fetch hooks such as `npm install` in child directories. This ensures Chromium, brave-core, and auxiliary repos are checked out to the correct revisions and ready for compilation.

### When should I use --force vs --init?

Use **`--force`** when your local tree is in an inconsistent state or you want to reset Chromium and brave-core to the latest remote commits while re-applying all patches. Use **`--init`** when performing a fresh checkout or after switching major release branches, as it forces Chromium and brave-core to the specific versions pinned in [`brave-core/package.json`](https://github.com/brave/brave-browser/blob/main/brave-core/package.json) rather than the latest tip.

### How do I skip the Chromium update during sync?

Pass the **`--sync_chromium=false`** flag after the double-dash: `npm run sync -- --sync_chromium=false`. This prevents the sync script from fetching a new Chromium revision, which is useful when you want to avoid triggering a lengthy rebuild of the Chromium engine while still updating brave-core or applying new patches.

### Where are the Brave patches stored and applied?

Brave-specific patches are stored as `*.patch` files throughout the repository. During the sync process, the Node.js script automatically discovers and applies these patches to the fetched Chromium and brave-core source trees after `gclient sync` completes but before running post-fetch hooks. This modifies upstream code to implement Brave-specific features and security enhancements.