# How to Set Up the Brave Browser Build Environment for Windows Development

> Set up the Brave Browser build environment on Windows. Follow steps to install Visual Studio, clone the repo, and compile the browser for Windows development.

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

---

**To build Brave Browser on Windows, install Visual Studio 2022 with the C++ workload, clone the `brave/brave-browser` repository, run `npm install` and `npm run init -- --target_os=win`, then use `gn gen` and `autoninja` to compile.**

Setting up the Brave Browser build environment for Windows development requires configuring a Chromium-based toolchain that integrates Brave-specific patches and dependencies. The `brave/brave-browser` repository serves as the entry point, orchestrating the download of Chromium source code via `depot_tools` and applying Brave-core modifications located in `src/brave`.

## Prerequisites for Windows Development

Building Brave on Windows depends on the same foundational tools used for Chromium, with specific version requirements enforced by the build scripts in [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json).

### Visual Studio 2022

Install **Visual Studio 2022** with the **"Desktop development with C++"** workload. The build system specifically requires:

- **MSVC v143** toolset (Visual Studio 2022)
- **Windows 10 SDK** (latest version available in the installer)

Verify installation by running `vswhere -latest -requires Microsoft.Component.MSBuild` from a command prompt.

### Python, Git, and Node.js

- **Python 3.10**: Required for Chromium's GN and GYP meta-build scripts. Ensure `python` is available in your `PATH`.
- **Git**: Needed for repository cloning and `depot_tools` operations.
- **Node.js ≥16 and npm**: The `brave-browser` repository uses npm scripts defined in [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json) to orchestrate the build process.

### depot_tools

**depot_tools** is Google's suite of build tools that includes `gclient`, `gn`, and `ninja`. Clone the repository and add it to the **front** of your system `PATH`:

```bash
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
set PATH=C:\path\to\depot_tools;%PATH%

```

## Clone the brave-browser Repository

Create a working directory with at least **150 GB** of free space, then clone the main repository:

```bash
mkdir C:\brave && cd C:\brave
git clone https://github.com/brave/brave-browser.git
cd brave-browser
git submodule update --init --recursive

```

This initializes the `brave-core` submodule mounted at `src/brave`, which contains the Brave-specific source code and patches referenced in `src/brave/DEPS`.

## Initialize the Build Environment

Install the npm dependencies and fetch the Chromium source code:

```bash
npm install
npm run init -- --target_os=win --target_arch=x64

```

The `npm run init` command performs several critical operations:

1. **Downloads Chromium**: Uses `depot_tools/gclient sync` to fetch the specific Chromium revision pinned in `src/brave/DEPS`.
2. **Applies Patches**: Automatically applies Brave-specific patches located in `src/brave/patches/` to the Chromium source tree.
3. **Installs Dependencies**: Fetches third-party libraries such as `adblock-rust` referenced in [`package.json`](https://github.com/brave/brave-browser/blob/main/package.json).

## Configure the Build with GN

Chromium uses the **GN** meta-build system to generate Ninja files. Create a build configuration in the `out` directory:

```bash
gn gen out\BraveDebug --args="is_debug=true is_component_build=true target_os=\"win\" target_cpu=\"x64\" symbol_level=1"

```

Key GN arguments for Windows development:

- **`target_os="win"`**: Configures the toolchain to use the Windows SDK.
- **`target_cpu="x64"`**: Builds 64-bit binaries (recommended for modern Windows).
- **`is_component_build=true`**: Enables component builds for faster incremental compilation during development.
- **`symbol_level=1`**: Reduces symbol generation time while maintaining stack traces.

For a release build optimized for distribution:

```bash
gn gen out\BraveRelease --args="is_debug=false is_component_build=false target_os=\"win\" target_cpu=\"x64\""

```

## Compile Brave Browser on Windows

Use `autoninja` (a wrapper around Ninja provided by `depot_tools`) to compile:

```bash
autoninja -C out\BraveDebug brave

```

The `autoninja` command automatically detects available CPU cores and parallelizes the build. The `brave` target builds the full desktop browser executable.

For release builds:

```bash
autoninja -C out\BraveRelease brave

```

## Run and Test Your Build

Launch the compiled browser directly:

```bash
out\BraveDebug\brave.exe

```

Alternatively, use the npm wrapper which configures the correct environment:

```bash
npm start Debug

```

### Running Tests

Execute the test suites to verify your build:

```bash

# Unit tests

npm run test brave_unit_tests

# Browser tests

npm run test brave_browser_tests

# JavaScript tests within brave-core

cd src\brave && npm run test-unit

```

These commands are documented in the [`CONTRIBUTING.md`](https://github.com/brave/brave-browser/blob/main/CONTRIBUTING.md) file under the testing workflow section.

## Troubleshooting Common Windows Build Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| `ninja` not recognized | `depot_tools` not in `PATH` | Add `C:\path\to\depot_tools` to the **front** of your system `PATH` and restart your terminal. |
| MSVC version mismatch | Visual Studio 2019 or older installed | Install Visual Studio 2022 with the "Desktop development with C++" workload and ensure MSVC v143 is selected. |
| `python` resolves to Python 2 | Legacy Python in `PATH` | Use `py -3` explicitly or reinstall Python 3.10 and prioritize it in your `PATH`. |
| Large download stalls | Insufficient disk space or network timeout | Ensure at least 200 GB free space; run `git config --global http.postBuffer 524288000` to increase Git buffer size. |
| Patch application failures | Corrupted Chromium source or stale patches | Run `npm run sync -- --force` to re-sync and re-apply patches from `src/brave/patches/`. |

## Summary

Setting up the Brave Browser build environment for Windows development involves installing Visual Studio 2022 with C++ support, configuring `depot_tools`, and using npm scripts to orchestrate the Chromium fetch and build process.

- Install **Visual Studio 2022** with the Desktop C++ workload and MSVC v143 toolset.
- Clone `brave/brave-browser` and initialize submodules with `git submodule update --init --recursive`.
- Run `npm install` followed by `npm run init -- --target_os=win --target_arch=x64` to fetch Chromium and apply Brave patches.
- Use `gn gen` to configure build arguments for Windows, then compile with `autoninja -C out\BraveDebug brave`.
- Launch with `out\BraveDebug\brave.exe` or `npm start Debug`, and run tests via `npm run test brave_unit_tests`.

## Frequently Asked Questions

### What version of Visual Studio is required to build Brave on Windows?

Brave Browser requires **Visual Studio 2022** with the "Desktop development with C++" workload installed. Specifically, you need the **MSVC v143** toolset and the latest Windows 10 SDK. Older versions like Visual Studio 2019 are not supported by the current Chromium codebase that Brave is built upon.

### How much disk space is needed to build Brave Browser on Windows?

You should allocate at least **150–200 GB** of free disk space. The build process downloads the entire Chromium source tree (approximately 20–30 GB), Brave-core source, various third-party dependencies defined in `src/brave/DEPS`, and generates build artifacts that can exceed 50 GB for debug builds with symbols.

### Why does `npm run init` fail with patch application errors?

Patch failures typically occur when the Chromium source code has been updated but the Brave patches in `src/brave/patches/` have not been refreshed, or if the source tree is corrupted. To resolve this, run `npm run sync -- --force` to re-synchronize the Chromium revision and re-apply all patches. If issues persist, delete the `src` directory and run `npm run init` again.

### Can I build Brave for Windows on a different operating system?

No, you cannot perform a native Windows build on macOS or Linux. The build system requires the Windows SDK, MSVC compiler, and Windows-specific headers that are only available on Windows. However, you can use a Windows virtual machine or cloud-based Windows instances (such as Azure VMs) to perform the build if you are developing from a different host OS.