# How Brave Browser Integrates Chromium and brave-core: A Technical Deep Dive

> Discover how Brave Browser integrates Chromium and brave-core using DEPS and gclient. Learn about patching and building Brave's unique binary with GN and Ninja.

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

---

**Brave Browser integrates Chromium and brave-core by using a DEPS file and the gclient dependency manager to pin specific revisions of both repositories into a unified source tree, then applies Brave-specific patches and builds the final binary using GN and Ninja.**

Understanding how Brave Browser integrates Chromium and brave-core is essential for developers looking to contribute to the browser or fork it for custom builds. The `brave/brave-browser` repository does not contain the actual browser source code; instead, it serves as a build orchestration layer that pulls together the Chromium engine and Brave's proprietary features through a sophisticated dependency management system.

## Repository Architecture Overview

The integration relies on a separation of concerns between three distinct components, each managed through automated synchronization tools.

### The brave-browser Repository

The `brave/brave-browser` repository contains only build scripts, configuration files, and patch sets. It acts as the entry point for developers, providing npm-based commands that abstract the underlying complexity of Chromium's build ecosystem. Key files include [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json), which defines the `npm run sync` and `npm run build` commands, and the `patches/` directory containing `.patch` files that modify Chromium behavior.

### brave-core and Chromium Sources

The actual source code resides in two external repositories:

- **Chromium**: Pulled from `https://chromium.googlesource.com/chromium/src`, providing the Blink rendering engine, V8 JavaScript runtime, and networking stack.
- **brave-core**: Pulled from `https://github.com/brave/brave-core`, containing Brave-specific implementations including Shields, Brave Rewards, the built-in ad-blocker, and Rust-based privacy components.

## Dependency Management with DEPS and gclient

The technical integration centers on a **DEPS** file located at `src/brave/DEPS` within the brave-browser checkout. This file declares the exact Git revisions (commit hashes) for both Chromium and brave-core that should be used for a given build, ensuring reproducible builds across different environments.

The **gclient** tool, which is part of Chromium's depot_tools, processes this DEPS file. When executed, `gclient sync` creates a unified source tree with the following structure:

```

src/
 ├─ brave/          ← brave-core checkout (Brave-specific code)
 └─ third_party/
      └─ chromium/  ← Chromium source

```

This approach allows Brave to maintain a **single source tree** where Chromium and brave-core code can reference each other directly during compilation, enabling tight integration between the engine and Brave's privacy features.

## The Sync Workflow: npm run sync

Developers initiate the integration process using npm commands defined in [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json). Running `npm run sync` (or `npm run sync -- --init` for a fresh checkout) executes a script that performs four critical operations:

1. **Downloads sub-projects**: Uses `gclient sync` to fetch the specific Chromium and brave-core revisions defined in `src/brave/DEPS`.
2. **Applies Brave-specific patches**: Iterates through the `patches/` directory, applying `.patch` files to modify Chromium source files where direct modification isn't feasible.
3. **Updates child dependencies**: Installs Rust crates, npm modules, and other secondary dependencies required by brave-core.
4. **Runs initialization hooks**: Executes post-sync scripts such as `npm install` within the pulled repositories to prepare the build environment.

```bash

# Clone the build orchestration repository

git clone https://github.com/brave/brave-browser.git
cd brave-browser

# Fetch Chromium and brave-core, apply patches, install dependencies

npm run sync -- --init

# Build a debug component (fastest for development)

npm run build -- Debug

# Launch the built browser

npm start Component

```

## Build Process Integration

Once synchronization completes, Brave uses Chromium's standard build system—**GN** (Generate Ninja) and **Ninja**—to compile the browser. The integration works by merging Brave's build configuration with Chromium's:

- **GN Templates**: Brave adds its own `.gn` and `.gni` files within `src/brave` that define how Brave-specific targets (like the Rewards service or Shields UI) should be built.
- **Source Merging**: The build graph includes source files from both `src/brave` (brave-core) and the Chromium tree, allowing Brave components to link against Chromium's base libraries.
- **Patch Integration**: Changes applied via the `patches/` directory modify Chromium's build files where necessary to include Brave targets in the final binary.

Because Chromium is built from source rather than linked as a precompiled library, all Brave modifications compile directly into the engine. This ensures **tight integration** and **performance parity** with Google Chrome while maintaining Brave's privacy-focused feature set.

## Why This Integration Approach?

Brave's architecture provides several technical advantages for maintaining a Chromium-based browser:

- **Precise Version Pinning**: The DEPS file creates reproducible builds by locking Chromium and brave-core to specific commits, preventing "works on my machine" issues.
- **Upstream Tooling Compatibility**: By using `gclient`, GN, and Ninja, Brave leverages Chromium's existing infrastructure for code review, continuous integration, and security auditing.
- **Modular Modifications**: Keeping Brave-specific code in brave-core and using patch files for minor Chromium tweaks makes it easier to rebase onto new Chromium versions and contribute changes upstream.

## Summary

- Brave Browser integrates Chromium and brave-core using a **DEPS** file at `src/brave/DEPS` and the **gclient** dependency manager to create a unified source tree.
- The `npm run sync` command orchestrates downloading specific revisions of both repositories, applying patches from the `patches/` directory, and installing dependencies.
- The build process uses standard Chromium tooling (**GN** and **Ninja**) to compile both engines together, ensuring tight integration and performance parity with Chrome.
- This architecture allows Brave to maintain precise version control, leverage upstream Chromium infrastructure, and modularize its privacy-focused features.

## Frequently Asked Questions

### What is the difference between brave-browser and brave-core?

The **brave-browser** repository contains build scripts, configuration files, and patch sets that orchestrate the build process but contains no browser source code. The **brave-core** repository contains the actual C++, Rust, and JavaScript implementation of Brave-specific features like Shields, Rewards, and the ad-blocker. brave-core is pulled in as a dependency during the `npm run sync` process.

### How does Brave keep Chromium up to date?

Brave maintains a `DEPS` file at `src/brave/DEPS` that specifies the exact Git revision (commit hash) of Chromium to use. When Brave engineers want to update the underlying engine, they modify this file to point to a newer Chromium commit, then run the sync and build process to verify compatibility. This approach allows Brave to rebase its patches and brave-core code onto new Chromium versions in a controlled, reproducible manner.

### What build system does Brave Browser use?

Brave uses the same build system as Chromium: **GN** (Generate Ninja) for build configuration and **Ninja** for actual compilation. The build process is initiated through npm commands like `npm run build`, which internally invoke GN to generate build files and Ninja to compile the unified source tree containing both Chromium and brave-core code.

### Where are Brave's Chromium patches stored?

Brave-specific modifications to upstream Chromium that cannot be implemented through brave-core alone are stored as `.patch` files in the `patches/` directory of the brave-browser repository. During the `npm run sync` process, these patches are automatically applied to the Chromium source tree, allowing Brave to modify the underlying engine while keeping changes modular and trackable.