Environment:Cypress io Cypress Browser Requirements
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Testing, Browser_Automation |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
Browser requirements for running Cypress tests, supporting Chromium-family browsers (Chrome, Edge, Chromium), Firefox >= 135, and the bundled Electron browser.
Description
Cypress detects and launches browsers installed on the user's system. The @packages/launcher module maintains a registry of known browsers with platform-specific detection logic for macOS, Linux, and Windows. Each browser family (Chromium, Firefox) has specific version validation rules. The bundled Electron browser (v37.6.0) is always available as a fallback. Firefox requires WebDriver BiDi support (version 135+) for Cypress compatibility.
Usage
Use this environment definition when running any Cypress E2E or component test. At least one supported browser must be installed and detectable. The Launchpad UI shows all detected browsers and marks unsupported versions with warnings.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Chromium Browsers | Chrome, Chrome Beta, Chrome Canary, Chrome for Testing, Chromium, Edge, Edge Beta, Edge Canary, Edge Dev | Any version currently supported |
| Firefox | >= 135 | Requires WebDriver BiDi; versions < 135 marked unsupported |
| Electron | 37.6.0 (bundled) | Always available; no separate install needed |
| macOS | Browsers detected via bundle identifiers and Info.plist | Uses `mdls` and `defaults read` commands |
| Linux | Browsers detected via binary names on PATH | Uses `which` command |
| Windows | Browsers detected via registry and known install paths | Uses PowerShell registry queries |
Dependencies
System Packages
- At least one of: `google-chrome`, `google-chrome-stable`, `firefox`, `chromium-browser`, `microsoft-edge` (Linux)
- At least one of: Google Chrome.app, Firefox.app, Microsoft Edge.app (macOS)
- At least one of: Chrome, Firefox, Edge installed (Windows — detected via registry)
Credentials
No credentials required for browser detection.
Quick Install
# Linux: Install Chrome
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update && sudo apt install -y google-chrome-stable
# Linux: Install Firefox (>= 135)
sudo apt install -y firefox
# Verify Cypress can detect browsers
npx cypress info
Code Evidence
Firefox version validation from `packages/launcher/lib/known-browsers.ts:3-20`:
const firefoxValidatorFn = (browser: FoundBrowser, platform: NodeJS.Platform): BrowserValidatorResult => {
try {
if (browser.majorVersion) {
const majorVersion = Number(browser.majorVersion)
if (majorVersion < 135) {
return {
isSupported: false,
warningMessage: `Cypress does not support running ${browser.displayName} version ${browser.majorVersion} due to lack of WebDriver BiDi support. To use ${browser.displayName} with Cypress, install version 135 or newer.`,
}
}
}
} catch (e) { /* empty */ }
return { isSupported: true }
}
Platform-specific detection dispatch from `packages/launcher/lib/detect.ts:63-67`:
const helpers: Helpers = {
darwin: darwinHelper,
linux: linuxHelper,
win32: windowsHelper,
}
Known browsers registry from `packages/launcher/lib/known-browsers.ts:23-143`:
export const knownBrowsers: Browser[] = [
{ name: 'chrome', family: 'chromium', channel: 'stable', displayName: 'Chrome',
binary: ['google-chrome', 'chrome', 'google-chrome-stable'] },
{ name: 'firefox', family: 'firefox', channel: 'stable', displayName: 'Firefox',
binary: 'firefox', validator: firefoxValidatorFn },
{ name: 'edge', family: 'chromium', channel: 'stable', displayName: 'Edge',
binary: ['edge', 'microsoft-edge'] },
// ... plus beta, canary, dev channels for each
]
Windows binary field bypass from `packages/launcher/lib/detect.ts:98`:
if (Array.isArray(browser.binary) && os.platform() !== 'win32') {
return Bluebird.map(browser.binary, (binary: string) => {
return checkOneBrowser(extend({}, browser, { binary }))
})
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Cypress does not support running Firefox version X due to lack of WebDriver BiDi support` | Firefox version < 135 | Upgrade Firefox to version 135 or newer |
| `Could not find helper for {platform}` | Running on unsupported OS | Cypress supports darwin, linux, win32 only |
| `No browsers detected` | No supported browser installed | Install Chrome, Firefox (>= 135), or Edge |
| Browser shows as "unsupported" in Launchpad | Browser version fails validation check | Update browser to supported version |
Compatibility Notes
- Firefox < 135: Explicitly unsupported due to missing WebDriver BiDi. The browser will appear in detection results but is marked as `unsupportedVersion: true` with a warning message.
- Chrome on Windows: Previous versions had a known blocking bug with Chrome 101-102 on Windows (now resolved). The validator infrastructure remains for future use.
- Linux binary names: Ubuntu PPAs may install Firefox Developer Edition as `firefox` rather than `firefox-developer-edition`. The launcher checks both binary names.
- Chromium vs Chrome: Chromium is treated as a separate browser from Chrome in the browser list. It uses a different version regex pattern.
- Electron: Always available as a bundled browser (v37.6.0). Used as the default for `cypress run` when no other browser is specified.