# brave-core: The Chromium Patch Layer Behind the Brave Browser

> brave-core is the repository of patches, build scripts, and component integrations that transforms Chromium into the Brave browser. It is aimed at browser engineers, not end users, and its initial build can take several hours.

**brave/brave-core** — Core engine for the Brave browser for mobile and desktop. For issues https://github.com/brave/brave-browser/issues

- Repository: https://github.com/brave/brave-core
- Stars: 3,624 · Forks: 1,447
- Language: C++
- License: MPL-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/brave-brave-core

## What brave-core Provides and Who Should Use It

brave-core is not a standalone application. It is a subfolder mounted at src/brave within a Chromium source tree, holding the changes that turn generic Chromium into the Brave browser. The repository holds build tools needed to assemble the Brave desktop browser for all platforms, as the README states. It also coordinates companion repositories: adblock-rust (Brave's ad-blocking engine linked through brave-core/components/adblock_rust_ffi), and all other dependencies declared in package.json and src/brave/DEPS.

The audience is browser engineers: contributors to Brave's open-source development, engineers at organizations building Brave-based products, and developers who need to audit or modify browser behavior at a level below what extensions permit. Someone who wants a faster, privacy-respecting browser without any source involvement should download the prebuilt binary from brave.com; building from source offers no additional capability for ordinary users and adds significant complexity.

## How the Chromium Customization Model Works

Brave's build model layers brave-core on top of Chromium rather than forking Chromium's repository. The patches directory holds diff files applied to Chromium source files during the init phase. This approach means brave-core can track upstream Chromium by running pnpm run sync, which re-applies patches and updates child dependencies, without needing to maintain a diverged copy of the entire Chromium tree.

The adblock-rust integration illustrates the design philosophy. Rather than rewriting ad-blocking in C++, the team linked a Rust library through an FFI layer at components/adblock_rust_ffi. The filtering engine lives in a separate repository and can be updated independently of Chromium internals. Similarly, the Chromium branch that brave-core targets is set in package.json; the version field in that file read 1.98.37 at the time of the last push, indicating which Chromium build is being tracked.

For platform coverage, the README lists Android, iOS, Linux, macOS, and Windows. iOS builds are handled separately through an Xcode project in ios/brave-ios/App rather than through the pnpm build chain used by desktop targets.

## Cloning, Initializing, and Running the First Build

The README requires that brave-core be checked out at a specific path, not into an arbitrary directory. First, clone into src/brave inside a project folder:

```bash
git clone git@github.com:brave/brave-core.git path-to-your-project-folder/src/brave
cd path-to-your-project-folder/src/brave
```

The next step fetches Chromium and resolves all dependencies. For a standard desktop build:

```bash
pnpm run init
```

For an Android build targeting arm:

```bash
pnpm run init --target_os=android --target_arch=arm
```

The README warns that this step downloads Chromium's large history, potentially tens of gigabytes, and may take a long time depending on connection speed. Once init finishes, start a component build:

```bash
pnpm run build
```

For a release build:

```bash
pnpm run build Release
```

Once built, launch the browser with pnpm start followed by the build type (Release, Component, Static, or Debug). The component build is the default and is faster to iterate on; the release build produces the final shipping binary but the README explicitly notes it can be very slow and memory-intensive, particularly on Linux with the Gold LLVM plugin.

## Build Configurations and Their Trade-offs

Four named build configurations appear in the README. The component build is the fastest for iterative development. The release build targets distribution quality but the README warns it can take hours and use substantial RAM on Linux. A static build takes longer to compile but produces a binary that starts faster. The debug build enables is_debug=true for development diagnostics.

The iOS path diverges from the others. Instead of running pnpm run build, iOS builds use the Xcode project at ios/brave-ios/App. Running pnpm run ios_bootstrap --open_xcodeproj opens that project in Xcode automatically.

A practical constraint the README surfaces is that no minimum hardware specification is given, while also warning that release builds are demanding. Teams without dedicated high-memory build machines should plan for the component build variant during development and reserve release builds for CI with purpose-allocated runners. The build will take a while to complete; depending on processor and memory, it could potentially take a few hours, as the documentation states.

## Updating the Source Tree with pnpm run sync

After initial setup, keeping the tree current requires pnpm run sync rather than a plain git pull on brave-core. The sync command coordinates multiple subprojects at once:

```bash
pnpm run sync [--force] [--init] [--create] [brave_core_ref]
```

Without flags, sync updates Chromium if needed, re-applies only changed patches, and updates child dependencies only when some project required an update during that run. The --force flag updates both Chromium and brave-core to the latest remote commit for the current branch and the Chromium ref in package.json. The README advises committing local changes in brave-core before running sync, noting that stashing will be attempted but is less reliable than a prior commit.

The brave_core_ref argument lets developers target a specific tag or branch, which is useful when aligning a fork against a known Brave release. Releases are not published from this repository; the brave/brave-browser repository holds release tags and the download page at brave.com.

## brave-core vs. ungoogled-chromium

ungoogled-chromium is the most direct comparison point: another project that applies patches on top of Chromium. The approaches diverge in purpose. ungoogled-chromium focuses on removing Google service dependencies entirely and ships no replacement service layer. brave-core replaces some Google services with Brave-specific alternatives, including the adblock-rust engine, Brave Rewards components, and Brave's own network services, while keeping others intact.

For an engineer studying privacy modifications without deploying a commercial product, ungoogled-chromium may suit the goal. For an engineer contributing to Brave or building on its service layer (such as Brave Rewards or the Brave-specific search integration), brave-core is the necessary foundation. The two repositories are not interchangeable: brave-core carries JavaScript components, pnpm-based build orchestration, and Brave's own service endpoints, none of which exist in ungoogled-chromium.

## Maintenance, License, and Contribution Process

The last push was on 2026-09-27, confirming that the repository receives daily updates. The project does not publish GitHub releases; finished releases appear under the brave/brave-browser companion repository.

The codebase is licensed under MPL-2.0, which requires that modifications to covered files be made available under the same terms. Contributions follow the guidelines in CONTRIBUTING.md and must pass presubmit checks defined in PRESUBMIT.py. Code style is enforced through .clang-tidy and .clangd configurations. Translation work is handled through Transifex rather than pull requests. A security policy exists in SECURITY.md; engineers submitting security-relevant patches should read that file before proceeding.

The repository includes a .github directory suggesting CI workflows, though the README does not detail their configuration.

## Conclusion

brave-core is the right starting point for engineers who need to modify Brave at the source level, contribute patches upstream, or maintain a Brave-based fork. Anyone who simply wants a privacy-focused browser should download the finished binary from brave.com rather than building from source. Before touching the build environment, verify the platform prerequisites on the brave-browser wiki for your target OS and confirm that you have tens of gigabytes free for the Chromium checkout. Check that your available RAM meets what a release build on Linux requires before targeting that configuration.

## FAQ

### What is BraveCore?

BraveCore, written as brave-core, is the repository that holds Brave's patches and build scripts for customizing Chromium into the Brave browser. It is not a standalone application; it is mounted at src/brave inside a Chromium source tree.

### What is brave core?

brave core is the source layer that contains Brave's Chromium modifications, including the adblock-rust integration, pnpm build scripts, and platform-specific patches for Linux, macOS, Windows, Android, and iOS.

### Can I build brave-core for Android or iOS?

Android builds use pnpm run init --target_os=android with the target CPU architecture as an argument. iOS builds go through an Xcode project at ios/brave-ios/App, opened with pnpm run ios_bootstrap --open_xcodeproj. Each platform requires following the platform-specific setup guide in the brave-browser wiki.

## Sources

- [brave/brave-core on GitHub](https://github.com/brave/brave-core)
- [Issues](https://github.com/brave/brave-core/issues)
- [License: MPL-2.0](https://github.com/brave/brave-core/blob/master/LICENSE)
- [README](https://github.com/brave/brave-core/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brave-brave-core