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.

​
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