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 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.
  • 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:
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.

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

​
Next steps