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

# Install command for managed browser runtimes

> Add a managed browser runtime to the Extension.js cache for deterministic builds. Supports Chrome for Testing, Chromium, Firefox, and Edge.

Use `install` to add a managed browser runtime into the Extension.js cache.

This is most useful when you want a consistent browser binary for `dev`, `build`, `start`, or `preview`. It supports Chrome for Testing, Chromium, Firefox, and Edge.

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

## When to use `install`

* You need a consistent, repeatable browser binary for continuous integration (CI), automation, or team-consistent local runs.
* You want Chrome for Testing instead of relying on whatever Chrome version your system has installed.
* You are setting up cross-browser testing with managed Firefox or Edge runtimes.

## Why Extension.js downloads a browser

The run commands prefer a managed browser runtime over the browser that you use every day.

* The managed binary is version-pinned. `dev`, CI runs, and teammates all launch the same build.
* Chrome for Testing is built for automation. Recent branded Chrome builds (150+) can drop the `--load-extension` switch that loads your extension.
* The managed runtime runs in an isolated profile. It never touches your personal browser, its profile, or its settings.

You do not have to run `install` up front. When no usable binary exists for the requested target, the run commands print the exact install command.

## Skip the managed download

You can develop against a browser that is already installed, with no download:

* Run a fork by name: `extension dev --browser=brave` locates the installed Brave for you. See [Running other browsers](/docs/browsers/running-other-browsers).
* Pin any binary: pass `--chromium-binary <path>` or `--gecko-binary <path>` to `dev`, `start`, or `preview`. The pin overrides every locator.
* Requested `edge` launches the Edge that is installed on your system when no managed Edge exists.
* Requested `chrome` refuses a branded system Chrome and asks for Chrome for Testing instead.
* To run branded Chrome anyway, pin it with `--chromium-binary`.

### When Edge is already installed

`--browser=edge` finds the system Edge on its own, so you can skip `extension install edge`. Run `extension install edge` only when you want a pinned managed copy for automation.

On Linux, the managed Edge download needs an interactive session with sudo rights. When that download fails and a system Edge exists, the installer reports the system binary and succeeds with it.

## Canonical usage

For a single browser, use the positional form:

<CodeGroup>
  ```bash npm theme={null}
  extension install <browser>
  ```

  ```bash pnpm theme={null}
  extension install <browser>
  ```

  ```bash yarn theme={null}
  extension install <browser>
  ```

  ```bash bun theme={null}
  extension install <browser>
  ```

  ```bash deno theme={null}
  # Needs Node.js on PATH: the download runs through npx.
  extension install <browser>
  ```
</CodeGroup>

Use `--browser` only when you need multiple targets, browser families, or `all`.

## Install command capabilities

| Capability | What it gives you |
| - | - |
| Managed browser cache | Stable install location under the Extension.js browser cache |
| Repeatable runtime | Consistent binaries for repeatable local runs and automation |
| Cross-browser setup | One command flow for Chrome, Chromium, Edge, and Firefox |
| Path discovery | `--where` reveals the resolved cache root or browser-specific install path |

## Usage

<CodeGroup>
  ```bash npm theme={null}
  extension install [browser-name] [options]
  ```

  ```bash pnpm theme={null}
  extension install [browser-name] [options]
  ```

  ```bash yarn theme={null}
  extension install [browser-name] [options]
  ```

  ```bash bun theme={null}
  extension install [browser-name] [options]
  ```

  ```bash deno theme={null}
  # Needs Node.js on PATH: the download runs through npx.
  extension install [browser-name] [options]
  ```
</CodeGroup>

## Arguments and flags

| Flag / argument | What it does | Default |
| - | - | - |
| `[browser-name]` | Install a single browser target such as `chrome`, `chromium`, `edge`, or `firefox` | `chromium` |
| `--browser <chrome\|chromium\|edge\|firefox\|chromium-based\|gecko-based\|firefox-based\|all>` | Override the positional browser name and support multi-target installs | unset |
| `--where` | Print the resolved managed cache root, or browser-specific install path | disabled |
| `--output <pretty\|json>` | Result format. `json` prints a schema-1 envelope on stdout | `pretty` |

### What `all` means here

`extension install --browser all` installs `chrome`, `chromium`, `edge`, and `firefox`. This differs from `--browser all` on the run commands, which expands to `chrome`, `edge`, and `firefox` only. The install set also covers Chromium because it is the default launch target for `dev` and `start`.

## Machine output with `--output json`

`--output json` prints one schema-1 envelope on stdout:

* A successful install prints a `status: "installed"` frame with the installed browsers in `value.browsers`.
* `--where` prints a `status: "located"` frame with the resolved paths in `value.paths`.
* A failed download prints `ok: false` with `error.code: "E_BROWSER_DOWNLOAD"` before the process exits `1`.
* A download that finishes without leaving a usable browser binary fails the same way. See [Behavior notes](#behavior-notes).

## Examples

### Install Chrome for Testing

```bash theme={null}
extension install chrome
```

### Install multiple targets in one command

```bash theme={null}
extension install --browser chrome,firefox
```

### Show the managed install path for Chrome

```bash theme={null}
extension install chrome --where
```

## Cache locations

By default, Extension.js stores managed browsers in a stable per-user cache:

* macOS: `~/Library/Caches/extension.js/browsers`
* Linux: `~/.cache/extension.js/browsers` or `$XDG_CACHE_HOME/extension.js/browsers`
* Windows: `%LOCALAPPDATA%\extension.js\browsers`

You can override the cache root with `EXT_BROWSERS_CACHE_DIR`.

### What the cache holds

Each browser gets its own folder under the cache root, but the layout inside differs by download engine:

* `chrome`, `chromium`, and `firefox` come from `@puppeteer/browsers`. Expect its nested platform and version folders inside each browser directory.
* `edge` comes from `playwright install msedge`, which lays the binary out in its own structure.
* `safari` has no download. Safari ships with macOS and needs the full Xcode app for builds, so `extension install safari` refuses with an explanation.
* Named forks such as Brave are never downloaded. Point at them with `--chromium-binary` or `--gecko-binary` instead.

Use `--where` instead of hardcoding paths, because the nested layout can change with the download engines.

### Project-local binaries

Set `EXTENSIONJS_BINARIES_IN_DIST=1` to make the run commands resolve managed binaries under `dist/extension-js/binaries` inside the project instead of the shared per-user cache. This suits sandboxed or fully self-contained project setups.

## Best practices

* **Use `install` in CI** to pin a consistent browser binary instead of relying on whatever the runner provides.
* **Prefer `chrome`** over `chromium` for Chrome for Testing: it matches stable Chrome behavior more closely.
* **Use `--where`** to verify cache paths before scripting automation around managed browsers.
* `install` only manages browsers inside the Extension.js cache. It does not modify system browser installs.

## Behavior notes

* `chrome` installs Chrome for Testing rather than relying on the system Google Chrome app.
* `edge` may require a privileged interactive session on Linux.
* `install` checks the destination before it reports success. When the installer exits cleanly but the folder holds no browser binary that is a non-empty executable file, as after an interrupted download, the command fails with `E_BROWSER_DOWNLOAD` and exits `1`. It removes the incomplete files, so the next `extension install` starts clean.
* On Deno, `install` needs Node.js on your `PATH`. The browser installer shells out to `npx`, or to the package manager that launched the CLI, to run the download engine, and `deno` has no such runner. Without Node.js the command fails at the download step. The other commands run on Deno alone.

## Next steps

* Remove managed browsers with [`uninstall`](/docs/commands/uninstall).
* Use managed browsers with [`dev`](/docs/commands/dev) and [`start`](/docs/commands/start).
* Learn about [Running other browsers](/docs/browsers/running-other-browsers) with custom binary paths.


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