> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Running other browsers from binary path

> Use your installed Chrome, Brave, Vivaldi, Waterfox or Firefox instead of a managed download by giving Extension.js an explicit binary path.

Run popular Chromium and Gecko forks either by name (Extension.js locates the
installed binary for you) or by providing an explicit binary path.

Test Brave, Opera, Vivaldi, Yandex, Waterfox, and LibreWolf from the same Extension.js workflow. Name the fork directly, or point at any custom binary with binary flags and `extension.config.*` in `dev`, `start`, and `preview`.

## Run a fork by name

These forks are first-class browser targets. Pass the name to `--browser` and Extension.js finds the installed binary on your system automatically, running it through its engine family's launcher:

| Browser target | Engine family | Auto-located |
| - | - | - |
| `brave` | Chromium | yes |
| `opera` | Chromium | yes |
| `vivaldi` | Chromium | yes |
| `yandex` | Chromium | yes |
| `waterfox` | Gecko | yes |
| `librewolf` | Gecko | yes |

```bash theme={null}
extension dev --browser=brave
```

```bash theme={null}
extension dev --browser=waterfox
```

If the browser is not installed, Extension.js exits with install guidance. A named fork inherits its family's manifest keys, so `chromium:`/`firefox:` prefixed fields resolve correctly (see [Browser-specific manifest fields](/docs/features/browser-specific-fields)).

<Note>
  The `dev`, `build`, `start`, and `preview` help output all list every fork
  name. The `start` and `preview` lists leave out `safari` and `webkit-based`
  because those two commands refuse Safari targets by design.
</Note>

## Run a custom binary

To run a browser without a built-in locator, or to override the located binary, use one of these flags:

* `--chromium-binary <path>`
* `--gecko-binary <path>` (alias: `--firefox-binary <path>`)

These binary flags override which browser binary Extension.js launches, regardless of the named browser target you selected.

## Binary capabilities

| Option / key | What it does |
| - | - |
| `--chromium-binary <path>` | Launches a custom Chromium-family browser binary. |
| `--gecko-binary <path>` | Launches a custom Gecko-family browser binary. |
| `--firefox-binary <path>` | Alias of `--gecko-binary`. |
| `browser.<target>.chromiumBinary` | Sets default custom Chromium binary in config. |
| `browser.<target>.geckoBinary` | Sets default custom Gecko binary in config. |
| `commands.<name>.chromiumBinary` | Sets command-specific custom Chromium binary. |
| `commands.<name>.geckoBinary` | Sets command-specific custom Gecko binary. |

### CLI examples

```bash theme={null}
extension dev --browser=chromium-based --chromium-binary="/path/to/brave"
```

```bash theme={null}
extension dev --browser=firefox --gecko-binary="/path/to/firefox-developer-edition"
```

You can also use them with `start` and `preview`.

## Find the binary path per OS

The binary flags expect an executable file. An invalid path fails fast with an error instead of launching.

### macOS

On macOS, an app such as `/Applications/Brave Browser.app` is a folder, not an executable. Pass the executable inside the bundle, at `Contents/MacOS`:

```bash theme={null}
extension dev --browser=chromium-based --chromium-binary="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
```

The executable name can differ from the app name. List the folder to find it:

```bash theme={null}
ls "/Applications/Brave Browser.app/Contents/MacOS"
```

### Windows

Quote the path and use forward slashes, which every shell accepts:

```bash theme={null}
extension dev --browser=chromium-based --chromium-binary="C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe"
```

Backslashes also work, but many shells require you to double them, as in `C:\\Program Files\\...`.

### Linux

Pass the executable that your package manager installed:

```bash theme={null}
extension dev --browser=chromium-based --chromium-binary="/usr/bin/brave-browser"
```

Run `which brave-browser` to print the path when the binary is on your `PATH`.

<Frame>
  <iframe className="w-full aspect-video rounded-xl" src="https://www.youtube-nocookie.com/embed/ihOvYKwT4sE?rel=0" title="Extension.js: run Brave with --chromium-binary" loading="lazy" allow="encrypted-media; picture-in-picture; fullscreen" allowFullScreen />
</Frame>

## Configure in `extension.config.*`

```js theme={null}
export default {
  browser: {
    "chromium-based": {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    "gecko-based": {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};
```

You can also place binary paths in command blocks:

```js theme={null}
export default {
  commands: {
    dev: {
      chromiumBinary: "/path/to/custom-chromium-browser",
    },
    preview: {
      geckoBinary: "/path/to/custom-gecko-browser",
    },
  },
};
```

## Target mapping behavior

Binary hints map to engine targets:

* `chromiumBinary` → `chromium-based`
* `geckoBinary` / `firefoxBinary` → `gecko-based`

If you provide both, Extension.js applies Chromium binary resolution first.

## Available browsers

Forks with a built-in locator run by name; anything else runs with a binary flag:

| Browser name | Type | How to run | Official website |
| - | - | - | - |
| **Brave** | Chromium-based browser | `--browser=brave` or `--chromium-binary` | [brave.com](https://brave.com) |
| **Opera** | Chromium-based browser | `--browser=opera` or `--chromium-binary` | [opera.com](https://www.opera.com) |
| **Vivaldi** | Chromium-based browser | `--browser=vivaldi` or `--chromium-binary` | [vivaldi.com](https://vivaldi.com) |
| **Yandex** | Chromium-based browser | `--browser=yandex` or `--chromium-binary` | [browser.yandex.com](https://browser.yandex.com) |
| **Waterfox** | Gecko-based browser | `--browser=waterfox` or `--gecko-binary` | [waterfox.com](https://www.waterfox.com) |
| **LibreWolf** | Gecko-based browser | `--browser=librewolf` or `--gecko-binary` | [librewolf.net](https://librewolf.net) |
| **Zen** | Gecko-based browser | `--browser=zen` or `--gecko-binary` | [zen-browser.app](https://zen-browser.app) |
| **Floorp** | Gecko-based browser | `--browser=floorp` or `--gecko-binary` | [floorp.app](https://floorp.app) |
| **Firefox Developer Edition** | Gecko-based browser | `--gecko-binary` | [firefox.com](https://www.mozilla.org/firefox/developer/) |

## Important constraints

* `chromium-based` requires `--chromium-binary` (or `chromiumBinary` in config). Without it the launch hard-exits with an error. There is no fallback to a system browser.
* `gecko-based` / `firefox-based` require a valid `geckoBinary` path.
* `librewolf` needs remote debugging turned on once per machine. LibreWolf resets `devtools.debugger.remote-enabled` to `false` at every start, which overrides the profile Extension.js creates, so the launch checks `~/.librewolf/librewolf.overrides.cfg` (`%USERPROFILE%\.librewolf\librewolf.overrides.cfg` on Windows) and stops with the two lines to add when they are missing:

  ```text theme={null}
  pref("devtools.debugger.remote-enabled", true);
  pref("devtools.debugger.prompt-connection", false);
  ```
* Invalid paths fail fast with a clear CLI/runtime error.
* `build` does not accept binary flags. You can use binary-based launching only with `dev`, `start`, and `preview`.

## Edge binary override

Set the `EDGE_BINARY` environment variable to launch `--browser=edge` from a specific binary, without touching config:

```bash theme={null}
EDGE_BINARY="/path/to/msedge" extension dev --browser=edge
```

If the path does not exist, the launch fails instead of silently falling back.

## Run without launching a browser

Sometimes the right browser count is zero, for example in containers, over SSH, or when you drive a browser yourself.

Pass `--no-browser` to `dev`, `start`, or `preview`:

```bash theme={null}
extension dev --no-browser
```

The dev loop stays complete. The server watches your files, and every rebuild broadcasts a reload. After the first successful compile, the terminal prints a `(no-browser mode)` banner that names the output folder.

Load that `dist/<browser>` folder into a browser that you already run. In Chromium browsers, choose "Load unpacked" at `chrome://extensions` with Developer mode on. The loaded extension keeps updating on save. See [`dev`](/docs/commands/dev) for readiness synchronization with `--wait`.

To make this the default for a command, set `noBrowser` in config. The CLI flag wins over the config value:

```js theme={null}
export default {
  commands: {
    dev: {
      noBrowser: true,
    },
  },
};
```

## Opt out of injected defaults

`dev`, `start`, and `preview` inject launch defaults into every session. One visible default is dark appearance. Chromium targets get the `--force-dark-mode` and `--enable-features=WebUIDarkMode` flags. Gecko targets get the matching dark preferences.

To keep your system appearance, list the flag in `excludeBrowserFlags`:

```js theme={null}
export default {
  browser: {
    "chromium-based": {
      chromiumBinary: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
      excludeBrowserFlags: ["--force-dark-mode"],
    },
  },
};
```

Excluding `--force-dark-mode` drops the whole appearance bundle, including the Gecko preferences. An exclude entry also matches by switch name, so `--enable-features` removes `--enable-features=WebUIDarkMode`. See [Browser flags](/docs/browsers/browser-flags) for the default flag list and the full exclusion rules.

## Best practices

* **Pair binaries with explicit browser target**: Use `--browser=chromium-based` or `--browser=gecko-based` for predictable intent.
* **Use absolute paths**: Avoid shell-dependent path resolution issues.
* **Version-pin in continuous integration (CI) runners**: Keep browser binary paths deterministic for automated checks.
* **Combine with profile/flags carefully**: Reuse the same profile and flag strategy used for named browser targets.

## Next steps

* Learn more about [Browser preferences](/docs/browsers/browser-preferences).
* Learn more about [Browser profile](/docs/browsers/browser-profile).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.