Skip to main content
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.

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 a managed Firefox, or with Edge.

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.
  • Pin any binary: pass --chromium-binary <path> or --gecko-binary <path> to dev, start, or preview. The pin overrides every locator.
  • Set a binary variable such as FIREFOX_BINARY. See Which binary runs.
  • Requested edge launches the Edge that is installed on your system.
  • Requested chrome refuses a branded system Chrome and asks for Chrome for Testing instead.
  • To run branded Chrome anyway, pin it with --chromium-binary.

Edge installs on your system

extension install edge runs playwright install msedge, which installs Microsoft Edge on your system. The Extension.js cache holds no pinned copy of Edge. --browser=edge finds the system Edge on its own, so you can skip the command when Edge is already installed. On Linux, that install needs an interactive session with sudo rights. When the install fails and a system Edge exists, the installer reports the system binary and succeeds with it.

Which binary runs

From the release after 4.1.39, dev, start, and preview choose the binary in one order for every browser:
  1. The flag, --chromium-binary or --gecko-binary.
  2. The environment variable of the browser.
  3. The managed binary from extension install.
  4. The system install.
A variable that names a missing path, or a file that cannot run, fails the launch with E_BROWSER_BINARY_INVALID. A bad variable is never skipped. The identity card says which step answered. (pinned with FIREFOX_BINARY) names the flag or the variable, and (system install) marks a browser from your system. A managed binary gets no note. ready.json carries the same fact in binaryProvenance and binaryPinnedBy. For Firefox, the managed step prefers a stable build over a nightly that sits in the same cache. When a nightly runs, the card says Firefox Nightly. Requested chrome still refuses a branded system Chrome. A variable that names branded Chrome is not taken, and the run continues with the managed binary. See How the binary is chosen.

Canonical usage

For a single browser, use the positional form:
Use --browser only when you need multiple targets, browser families, or all.

Install command capabilities

Usage

Arguments and flags

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.

Examples

Install Chrome for Testing

Install multiple targets in one command

Show the managed install path for Chrome

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 is not in the cache. playwright install msedge installs Microsoft Edge on your system.
  • 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 keeps chrome, chromium, and firefox inside the Extension.js cache. It leaves system installs of those browsers alone.
  • edge is the exception. It installs Microsoft Edge on your system.

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