# How Brave Manages the DEPS File for Chromium Dependency Synchronization

> Learn how Brave manages its DEPS file for Chromium dependency synchronization using a partial DEPS file that extends and overrides upstream dependencies, synchronized securely via gclient sync.

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

---

**Brave uses a partial DEPS file located at `src/brave/DEPS` that extends and overrides upstream Chromium dependencies, synchronized via `gclient sync` and gated by CI validation.**

The `brave/brave-browser` repository maintains a complex dependency relationship with upstream Chromium, requiring precise version control to ensure stability and security. The **DEPS file** serves as the single source of truth for Chromium revisions, allowing Brave to pin specific versions while applying proprietary patches and extensions.

## Understanding the DEPS File Architecture

Brave's dependency management relies on a two-layer system that combines upstream Chromium configurations with Brave-specific overrides.

### The Base Chromium DEPS

The upstream Chromium source contains a root `DEPS` file that enumerates all Chromium-owned dependencies, including third-party libraries, testing tools, and build dependencies. This file lives in the Chromium repository and defines the baseline versions that Brave extends.

### Brave's Partial DEPS Override

Brave adds its own **`src/brave/DEPS`** file that *extends* and *overrides* entries in the Chromium DEPS. This partial DEPS file pins Brave-specific components including:

- The exact **Chromium version** via the `chromium_version` variable
- Brave-specific patches located in the `patches/` directory
- Ad-blocking libraries and privacy components not present in Chromium

## The Synchronization Workflow

Synchronizing dependencies requires coordinating `gclient` configuration with Brave's build scripts.

### gclient Configuration

The **`src/.gclient`** file defines the "solution" that tells `gclient sync` where to fetch Chromium and how to apply the Brave overlay. This configuration ensures that Chromium is fetched into `src/chrome` before Brave's modifications are applied.

### Running the Sync Command

Developers trigger synchronization using the npm shortcut defined in [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json):

```bash

# Sync the entire source tree (Chromium + Brave patches)

npm run sync

```

This command executes `gclient sync`, which reads the merged DEPS configuration, pulls the exact Chromium revision specified in `src/brave/DEPS`, and applies Brave's patches from the `patches/` directory.

To verify the specific Chromium revision that was fetched:

```bash
git -C src/chrome rev-parse HEAD

```

The output should match the revision hash defined in `src/brave/DEPS`.

### Chromium Version Bumping Process

When a new Chromium version is released, Brave maintainers follow a disciplined bump process using the **[`.github/ISSUE_TEMPLATE/06_chromium_bump.yml`](https://github.com/brave/brave-browser/blob/main/.github/ISSUE_TEMPLATE/06_chromium_bump.yml)** template. The process involves:

1. Updating the `chromium_version` variable in `src/brave/DEPS`
2. Running `npm run sync` to verify the checkout and apply patches
3. Updating related build scripts such as [`src/tools/update_brave_version.py`](https://github.com/brave/brave-browser/blob/main/src/tools/update_brave_version.py)
4. Submitting the change for CI validation

Example update to `src/brave/DEPS`:

```bash

# Update the Chromium revision in src/brave/DEPS

sed -i.bak 's/"chromium_version": ".*"/"chromium_version": "124.0.6367.91"/' src/brave/DEPS

# Re-run the sync to pull the new revision and apply Brave patches

npm run sync

# Commit the validated change

git add src/brave/DEPS
git commit -m "Bump Chromium to 124.0.6367.91"

```

## Continuous Integration and Validation

Brave's CI system enforces DEPS consistency on every pull request. The **[`.github/workflows/pull_request.yml`](https://github.com/brave/brave-browser/blob/main/.github/workflows/pull_request.yml)** workflow runs `gclient sync` before each build, guaranteeing that the exact revisions recorded in `src/brave/DEPS` are used. Any mismatch between the DEPS specification and the actual checked-out code causes the CI to fail, preventing accidental dependency drift.

## Key Files in the DEPS System

| File | Role |
|------|------|
| `src/brave/DEPS` | Brave-specific dependency overrides that pin the Chromium version and define Brave-specific components |
| `src/.gclient` | gclient configuration specifying how to fetch Chromium and apply the Brave overlay |
| [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json) | Contains the `npm run sync` script shortcut for developers |
| [`.github/ISSUE_TEMPLATE/06_chromium_bump.yml`](https://github.com/brave/brave-browser/blob/main/.github/ISSUE_TEMPLATE/06_chromium_bump.yml) | Issue template for coordinated Chromium version bumps |
| [`.github/workflows/pull_request.yml`](https://github.com/brave/brave-browser/blob/main/.github/workflows/pull_request.yml) | CI workflow that validates DEPS synchronization on every PR |

## Summary

- Brave uses a **partial DEPS file** at `src/brave/DEPS` to extend upstream Chromium dependencies without modifying the root Chromium repository.
- The **`chromium_version`** variable in `src/brave/DEPS` serves as the single source of truth for which Chromium revision Brave builds against.
- **gclient sync** (via `npm run sync`) merges the Chromium and Brave DEPS configurations, fetches the exact revisions, and applies Brave-specific patches.
- A **structured bump process** using GitHub issue templates ensures coordinated updates to Chromium versions with full CI validation.
- Continuous integration enforces DEPS consistency by running `gclient sync` on every pull request, preventing dependency drift.

## Frequently Asked Questions

### How does Brave pin a specific Chromium version without forking the entire Chromium repository?

Brave stores a `chromium_version` variable in `src/brave/DEPS` that specifies the exact revision hash or tag to fetch. When `gclient sync` runs, it reads this variable and checks out the specified Chromium revision into `src/chrome`, allowing Brave to build against a specific upstream version while keeping its own modifications separate in `src/brave`.

### What happens if the DEPS file specifies a Chromium revision that is incompatible with Brave's patches?

The CI system will fail during the `gclient sync` or patch application phase. Brave maintains a `patches/` directory containing modifications to Chromium source files. If a Chromium bump changes the underlying code that a patch targets, the patch will fail to apply cleanly, causing the build to break. This signals maintainers to update the affected patches before the new Chromium version can be adopted.

### Can developers manually override the Chromium version for local testing?

Yes, developers can manually edit `src/brave/DEPS` to change the `chromium_version` value to a different revision hash or tag. After modifying the file, running `npm run sync` (which invokes `gclient sync`) will fetch the new Chromium version and attempt to apply Brave's patches. However, this is not recommended for production builds as it bypasses the validated bump process and may introduce instability or security vulnerabilities.