# How the Brave Browser Build System Handles Chromium Patches: A Complete Technical Guide

> Learn how the Brave Browser build system manages Chromium patches. Discover how Brave integrates custom patches into the Chromium source during the npm run sync process.

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

---

**The Brave Browser build system handles Chromium patches by pulling the upstream Chromium source via depot_tools and then applying Brave-specific `.patch` files using a Node.js script ([`apply_patches.js`](https://github.com/brave/brave-browser/blob/main/apply_patches.js)) during the `npm run sync` process.**

The `brave/brave-browser` repository does not ship Chromium source code directly. Instead, it implements a sophisticated patch management system that layers Brave-specific modifications on top of the upstream Chromium codebase. Understanding how the Brave Browser build system handles Chromium patches is essential for developers contributing to the browser's core functionality or maintaining its fork of the Chromium engine.

## The Patch Application Architecture

Brave's build system uses a layered approach to modify Chromium, keeping Brave-specific changes isolated from the upstream source while ensuring they are applied consistently across builds.

### Repository Structure and Chromium Acquisition

The build process begins with **depot_tools**, Google's suite of build utilities for Chromium. The `src/brave/DEPS` file records the exact Chromium revision that Brave depends on, ensuring reproducible builds across different environments.

When you run the sync command, the build system:
1. Checks the current Chromium revision against the target revision in `DEPS`
2. Downloads the correct Chromium source if versions differ
3. Prepares the source tree for patch application

### The Patch Storage System

Brave stores all Chromium modifications as plain text **`.patch`** files within the repository. These files live in the `src/brave/patches/` directory (relative to the full source tree) and are version-controlled alongside the rest of the Brave codebase.

Each patch file represents a `git diff` that can be applied cleanly to the matching Chromium revision. This approach provides several advantages:
- **Transparency**: Changes to Chromium are visible as standard diff files
- **Reviewability**: Patches undergo normal code review processes
- **Portability**: Patches can be regenerated or moved between Chromium versions

## How the Brave Build System Applies Chromium Patches

The patch application process is orchestrated through npm scripts defined in [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json), providing developers with simple commands to manage the complex underlying operations.

### The Sync Command (`npm run sync`)

The primary entry point for patch management is `npm run sync`. This command handles the complete workflow of updating Chromium and applying patches:

```bash

# Standard development sync – updates Chromium if needed and reapplies changed patches

npm run sync

```

During execution, the sync script:
- Compares the current `DEPS` version against the previously synced version
- Runs `gclient sync` to fetch Chromium updates if the revision changed
- Calls [`apply_patches.js`](https://github.com/brave/brave-browser/blob/main/apply_patches.js) to layer Brave modifications on top of the fresh Chromium source
- Updates child dependencies and runs post-sync hooks

### Incremental vs. Full Patch Application

The build system optimizes for developer efficiency by minimizing unnecessary work. When the Chromium version has not changed between syncs, the system only reapplies patches that have been modified, significantly speeding up incremental builds.

However, when Chromium updates or when the repository state becomes inconsistent, you may need a complete refresh:

```bash

# Force a full Chromium checkout and re-apply every patch

npm run sync -- --force

```

The `--force` flag ensures a clean state by re-downloading Chromium and applying all patches from scratch, which is useful after problematic merges or when debugging patch conflicts.

### Explicit Patch Application (`npm run apply_patches`)

For scenarios where you have modified only patch files and want to avoid the overhead of a full sync, Brave provides a dedicated command:

```bash

# Only re-apply patches – skip Chromium version check

npm run apply_patches

```

This command executes [`scripts/apply_patches.js`](https://github.com/brave/brave-browser/blob/main/scripts/apply_patches.js) directly, iterating over all `*.patch` files in the patches directory and applying each one using `git apply`. This is the fastest path when you are iterating on patch development or fixing patch conflicts without changing Chromium versions.

## Technical Implementation Details

The actual patch application logic resides in [`scripts/apply_patches.js`](https://github.com/brave/brave-browser/blob/main/scripts/apply_patches.js), a Node.js utility that bridges the npm build commands with Git's patching capabilities.

The script operates by:
1. Locating the patches directory (`src/brave/patches` relative to the project root)
2. Enumerating all files ending in `.patch`
3. Executing `git apply` for each patch file against the Chromium source tree

Here is a simplified representation of the core logic:

```javascript
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

const patchesDir = path.join(__dirname, '..', 'src', 'brave', 'patches');

// Read all patch files from the directory
fs.readdirSync(patchesDir)
  .filter(f => f.endsWith('.patch'))
  .forEach(patch => {
    const patchPath = path.join(patchesDir, patch);
    console.log(`Applying ${patch}...`);
    
    // Apply the patch using git apply
    execSync(`git apply ${patchPath}`, { stdio: 'inherit' });
  });

```

This implementation ensures that patches are applied atomically and that any failure in one patch (due to conflicts with upstream changes) will be immediately visible to the developer, allowing for rapid iteration on patch maintenance.

## Summary

- **Brave does not fork Chromium directly**; instead, it maintains a set of `.patch` files in `src/brave/patches/` that modify the upstream source after checkout.
- **`npm run sync`** orchestrates the complete workflow, pulling the correct Chromium revision defined in `src/brave/DEPS` and automatically applying patches.
- **Incremental builds optimize performance** by only reapplying modified patches when the Chromium version remains unchanged.
- **`npm run apply_patches`** provides a fast path for developers iterating on patch files without triggering a full Chromium sync.
- **[`scripts/apply_patches.js`](https://github.com/brave/brave-browser/blob/main/scripts/apply_patches.js)** implements the core logic, using `git apply` to layer each patch onto the Chromium source tree.

## Frequently Asked Questions

### Where are the Chromium patches stored in the Brave repository?

Brave stores all Chromium modifications as plain text `.patch` files in the `src/brave/patches/` directory (relative to the full source tree). These files are version-controlled alongside the rest of the codebase and contain standard `git diff` output that can be applied to the matching Chromium revision.

### What is the difference between `npm run sync` and `npm run apply_patches`?

`npm run sync` is the comprehensive command that updates Chromium to the revision specified in `src/brave/DEPS`, syncs dependencies, and then applies patches. It is the standard command for daily development. In contrast, `npm run apply_patches` only runs the patch application step using [`scripts/apply_patches.js`](https://github.com/brave/brave-browser/blob/main/scripts/apply_patches.js), making it faster when you have only modified patch files and do not need to update the underlying Chromium source.

### How does Brave handle patch failures during the build process?

When a patch fails to apply—usually due to upstream Chromium changes that conflict with Brave's modifications—the `git apply` command invoked by [`scripts/apply_patches.js`](https://github.com/brave/brave-browser/blob/main/scripts/apply_patches.js) will exit with an error. This halts the build process immediately, alerting the developer to the conflict. The developer must then manually resolve the conflict by updating the patch file to match the new Chromium source, ensuring that Brave's modifications remain compatible with the upstream codebase.

### Can I force a complete re-application of all patches without updating Chromium?

Yes. While `npm run apply_patches` will re-apply all existing patches to the current Chromium tree, you can also use `npm run sync -- --force` to force a complete fresh checkout of Chromium followed by a full re-application of every patch. The `--force` flag is particularly useful when the repository state has become inconsistent or when debugging complex patch conflicts that require a clean slate.