> ## 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

> Test extensions in Brave, Vivaldi, Waterfox, or other Chromium and Gecko browsers by providing an explicit binary path to Extension.js.

<AvatarBrowsers browsers={["waterfox", "opera", "brave"]} />

Run Chromium- and Gecko-family browsers beyond the default named targets by
providing explicit binary paths.

Test custom browser binaries (for example, Brave, Vivaldi, or Waterfox) from the same Extension.js workflow. Use binary flags and `extension.config.*` in `dev`, `start`, and `preview`.

## How it works

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`.

## 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

Common browsers you can run with binary flags:

| Browser name                  | Type                   | CLI flag            | Official website                                          |
| ----------------------------- | ---------------------- | ------------------- | --------------------------------------------------------- |
| **Brave**                     | Chromium-based browser | `--chromium-binary` | [brave.com](https://brave.com)                            |
| **Opera**                     | Chromium-based browser | `--chromium-binary` | [opera.com](https://www.opera.com)                        |
| **Vivaldi**                   | Chromium-based browser | `--chromium-binary` | [vivaldi.com](https://vivaldi.com)                        |
| **Waterfox**                  | Gecko-based browser    | `--gecko-binary`    | [Waterfox](https://www.waterfox.net)                      |
| **Firefox Developer Edition** | Gecko-based browser    | `--gecko-binary`    | [firefox.com](https://www.mozilla.org/firefox/developer/) |

## Important constraints

* `chromium-based` requires a valid `chromiumBinary` path.
* `gecko-based` / `firefox-based` require a valid `geckoBinary` path.
* 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`.

## 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).