# How to Create Custom Build Variants and Branding for Brave Browser

> Create custom build variants and branding for Brave Browser. Learn how to set GN arguments, provide branding resources, and override strings for your unique browser build.

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

---

**You can create custom build variants and branding for Brave by setting GN arguments like `brave_product` and `brave_variant` in your `args.gn` file, then providing matching branding resources in `src/brave/app/branding/` and string overrides in `src/brave/branding/`.**

Brave's desktop browser is built on Chromium and uses the GN (Generate Ninja) build system. Custom build variants—such as debug versus release builds, specialized feature sets, or entirely rebranded browsers—are controlled through GN arguments and a structured set of branding resources within the `brave/brave-browser` repository. This guide explains how to leverage these mechanisms to generate tailored Brave binaries.

## Understanding Brave's Build System Architecture

Brave extends Chromium's build infrastructure, storing configuration in `src/brave/BUILD.gn` and related `.gni` files. The build process reads from `args.gn` to determine target architecture, build type, and product branding. Key files include `src/brave/branding/product.gni` for product name constants and `src/brave/app/branding/` for visual assets like icons and splash screens.

## Controlling Build Variants with GN Arguments

Build variants in Brave are defined through GN arguments that modify compilation flags, feature sets, and target platforms.

### Essential GN Arguments for Custom Builds

The primary arguments for controlling build variants reside in your `out/[BuildName]/args.gn` file:

- **`is_debug`** – Set to `true` for Debug builds or `false` for Release builds.
- **`is_component_build`** – Set to `true` to build shared libraries instead of a single static binary, significantly speeding up incremental builds.
- **`target_os`** and **`target_cpu`** – Specify cross-compilation targets such as `target_os = "linux"` and `target_cpu = "arm64"`.

These arguments are processed during the `gn gen` phase and affect how `src/brave/BUILD.gn` constructs the build graph.

### Creating Custom Feature Variants

You can define custom feature groups using the `brave_variant` variable, typically declared in `src/brave/branding/variant.gni` or similar configuration files:

```gn

# In your args.gn

brave_variant = "my_custom_variant"

```

This variable enables conditional compilation in `src/brave/BUILD.gn`:

```gn
if (brave_variant == "my_custom_variant") {
  # Enable experimental features or different code paths

  defines += [ "ENABLE_MY_CUSTOM_FEATURE" ]
}

```

## Implementing Custom Branding in Brave

Custom branding allows you to change the product name, icons, UI strings, and theme colors without modifying core source code.

### Product Name and Strings

Product names are controlled through `brave_product` and associated `.gni` files. Set the product identifier in `args.gn`:

```gn
brave_product = "mybrand"

```

Then create `src/brave/branding/mybrand/product_name.gni`:

```gn
brave_product_name = "MyBrowser"
brave_product_full_name = "MyBrowser – Private by Default"

```

These constants propagate to `src/brave/ui/strings/*.grd` files, which define the UI text resources. Duplicate the existing `.grd` files in a `mybrand` subdirectory and replace instances of "Brave" with your brand name.

### Icons and Visual Assets

Visual assets reside in `src/brave/app/branding/`. To use custom icons:

1. Create a new directory: `src/brave/app/branding/mybrand/`
2. Copy and modify assets from `src/brave/app/branding/default/` (or `brave/`)
3. Ensure your assets match the required sizes and formats (PNG for icons, SVG for scalable graphics)

Update `src/brave/app/branding/branding.gni` to conditionally import your assets:

```gn
if (brave_product == "mybrand") {
  import("//src/brave/app/branding/mybrand/branding_mybrand.gni")
} else {
  import("//src/brave/app/branding/default/branding_default.gni")
}

```

In `branding_mybrand.gni`, define the paths to your icon files:

```gn
brave_branding_path = "//src/brave/app/branding/mybrand"
brave_logo_path = "$brave_branding_path/logo.png"
brave_icon_256_path = "$brave_branding_path/icon_256.png"

```

### Theme Colors and UI Customization

Theme colors are defined in `src/brave/ui/theme/theme_color.gni`. Override these in your custom branding file:

```gn
brave_theme_color = "0xFF1E90FF"  # Dodger Blue instead of Brave Orange

```

This constant feeds into the Chromium theme system, affecting toolbar backgrounds and dialog highlights throughout the browser UI.

## Step-by-Step Workflow for Custom Brave Builds

Follow this complete workflow to generate a custom-branded Brave binary:

1. **Clone and sync the repository**:
   ```bash
   git clone https://github.com/brave/brave-browser.git
   cd brave-browser
   npm run sync
   ```

2. **Generate build configuration**:
   ```bash
   gn gen out/MyBuild
   ```

3. **Configure build arguments** by editing `out/MyBuild/args.gn`:
   ```gn
   is_debug = false
   target_os = "linux"
   target_cpu = "x64"
   brave_product = "mybrand"
   brave_variant = "myvariant"
   ```

4. **Create branding resources**:
   - Create `src/brave/app/branding/mybrand/` with custom icons
   - Create `src/brave/branding/mybrand/product_name.gni` with custom strings
   - Update `src/brave/app/branding/branding.gni` to import your resources conditionally

5. **Regenerate and build**:
   ```bash
   gn gen out/MyBuild
   npm run build Release
   ```

6. **Verify the output**:
   ```bash
   out/MyBuild/Brave Browser
   ```

   Confirm that the window title, about dialog, and icons reflect your custom branding.

## Code Examples and Configuration Files

### Custom GN Arguments File

```gn

# out/MyBuild/args.gn

is_debug = false
is_component_build = false
target_os = "linux"
target_cpu = "x64"

# Custom branding and variant selection

brave_product = "mybrand"
brave_variant = "enterprise"

```

### Branding Resource Import Logic

```gn

# src/brave/app/branding/branding.gni

if (brave_product == "mybrand") {
  import("//src/brave/app/branding/mybrand/branding_mybrand.gni")
  branding_assets_path = "//src/brave/app/branding/mybrand"
} else if (brave_product == "brave") {
  import("//src/brave/app/branding/brave/branding_brave.gni")
  branding_assets_path = "//src/brave/app/branding/brave"
}

```

### Product Name Definition

```gn

# src/brave/branding/mybrand/product_name.gni

brave_product_name = "MyEnterpriseBrowser"
brave_product_full_name = "MyEnterpriseBrowser – Secure by Design"
brave_product_short_name = "MEB"

```

### Feature Flag Conditional

```gn

# src/brave/feature_flags.gni

declare_args() {
  enable_enterprise_vpn = false
}

if (brave_variant == "enterprise") {
  enable_enterprise_vpn = true
}

```

## Summary

- **GN arguments** in `args.gn` control build variants through variables like `is_debug`, `target_cpu`, and custom variables such as `brave_variant`.
- **Custom branding** is implemented by setting `brave_product` and providing replacement assets in `src/brave/app/branding/[product]/` and string definitions in `src/brave/branding/[product]/`.
- The **branding import pattern** uses conditional GN imports in `src/brave/app/branding/branding.gni` to select the correct resource set at build time.
- **Product strings** are defined in `.gni` files and propagate to UI resources through the GRD (Google Resource Description) system used by Chromium.
- No source code modifications are required—only GN configuration files and asset replacements—to create a fully custom-branded Brave binary.

## Frequently Asked Questions

### What is the difference between `brave_product` and `brave_variant` in Brave's build system?

**`brave_product`** selects the branding identity—controlling the product name, icons, and visual assets—while **`brave_variant`** enables or disables specific feature sets or build configurations. For example, you might set `brave_product = "mybrand"` for custom enterprise branding and `brave_variant = "enterprise"` to activate VPN or policy features specific to that deployment.

### Do I need to modify C++ source code to change the product name in Brave?

**No.** The product name and branding are controlled entirely through GN build files and resource assets. By creating a new directory under `src/brave/branding/[your_product]/` with a `product_name.gni` file defining `brave_product_name` and `brave_product_full_name`, and updating `src/brave/app/branding/branding.gni` to import your assets, the build system automatically substitutes your branding throughout the UI without touching C++ source files.

### How do I create a debug build versus a release build for a custom Brave variant?

**Set `is_debug` in your `args.gn` file.** For a debug build, use `is_debug = true` and optionally `is_component_build = true` to enable shared libraries for faster incremental compilation. For a release build, set `is_debug = false` and `is_component_build = false` to produce a fully optimized static binary. After editing `args.gn`, run `gn gen out/[YourBuild]` to regenerate the build configuration before compiling with `npm run build`.

### Where should I place custom icon files when rebranding Brave?

**Place them in `src/brave/app/branding/[your_product]/`.** Create a new directory matching your `brave_product` value (e.g., `mybrand/`) and include PNG files for each required icon size (typically 16, 32, 48, 128, and 256 pixels) plus any SVG source files. Then create a `branding_[your_product].gni` file in that directory defining variables like `brave_icon_256_path` pointing to your assets, and import this file conditionally in `src/brave/app/branding/branding.gni` when `brave_product == "mybrand"`.