Environment:Microsoft Playwright Platform Support Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Browser_Automation |
| Last Updated | 2026-02-11 22:00 GMT |
Overview
Cross-platform support matrix covering Windows x64, macOS (Intel and Apple Silicon), and Linux (Ubuntu, Debian, and derivatives) for Playwright browser automation.
Description
Playwright implements detailed platform detection logic in `hostPlatform.ts` to determine the host operating system, version, and CPU architecture. This detection drives browser binary selection, native dependency resolution, and platform-specific workaround activation. The system supports 15+ distinct platform identifiers, with official support for major Ubuntu, Debian, Windows, and macOS versions. Ubuntu-derivative distributions (Pop!_OS, KDE Neon, TUXEDO OS, Linux Mint) are mapped to their corresponding Ubuntu versions with best-effort support.
Usage
This environment applies to all Playwright operations. The platform detection runs at module load time and affects browser binary downloads, native dependency validation, and runtime behavior. Platform-specific workarounds are activated based on the detected platform.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS — Windows | Windows 7 SP1+ (x64) | `win64` platform identifier |
| OS — macOS | macOS 10.13+ (Intel), macOS 11+ (Apple Silicon) | Auto-detects Intel vs ARM64 via CPU model |
| OS — Ubuntu | 20.04, 22.04, 24.04 (x64/arm64) | Officially supported versions |
| OS — Debian | 11, 12, 13 (x64/arm64) | Including `testing` and `unstable` (mapped to 13) |
| Architecture | x64 or arm64 | On Linux, other architectures return `<unknown>` |
| GPU (macOS) | Metal support | Checked for WebKit hardware acceleration |
Dependencies
Platform Detection
The `hostPlatform.ts` module detects the following platform identifiers:
Windows:
- `win64`
macOS (Intel):
- `mac10.13`, `mac10.14`, `mac10.15`, `mac11`, `mac12`, `mac13`, `mac14`, `mac15`
macOS (Apple Silicon):
- `mac11-arm64`, `mac12-arm64`, `mac13-arm64`, `mac14-arm64`, `mac15-arm64`
Linux (x64 and arm64):
- `ubuntu18.04-{arch}`, `ubuntu20.04-{arch}`, `ubuntu22.04-{arch}`, `ubuntu24.04-{arch}`
- `debian11-{arch}`, `debian12-{arch}`, `debian13-{arch}`
Distribution Mapping
- Pop!_OS, KDE Neon, TUXEDO OS: Mapped directly to Ubuntu versions (same major version)
- Linux Mint: Mint 20 → Ubuntu 20.04, Mint 21 → Ubuntu 22.04, Mint 22+ → Ubuntu 24.04
- Raspbian: Mapped to corresponding Debian versions
- Unknown Linux: Falls back to `ubuntu24.04-{arch}`
Credentials
- `PLAYWRIGHT_HOST_PLATFORM_OVERRIDE`: Override auto-detected platform (for testing or cross-compilation)
Quick Install
# Check your detected platform
npx playwright --version
# Override platform detection (advanced)
PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu22.04-x64 npx playwright install
Code Evidence
Platform detection from `packages/playwright-core/src/server/utils/hostPlatform.ts:40-46`:
function calculatePlatform(): { hostPlatform: HostPlatform, isOfficiallySupportedPlatform: boolean } {
if (process.env.PLAYWRIGHT_HOST_PLATFORM_OVERRIDE) {
return {
hostPlatform: process.env.PLAYWRIGHT_HOST_PLATFORM_OVERRIDE as HostPlatform,
isOfficiallySupportedPlatform: false
};
}
macOS version and ARM64 detection from `hostPlatform.ts:58-66`:
const LAST_STABLE_MACOS_MAJOR_VERSION = 15;
// Best-effort support for MacOS beta versions.
macVersion = 'mac' + Math.min(ver[0] - 9, LAST_STABLE_MACOS_MAJOR_VERSION);
// BigSur is the first version that might run on Apple Silicon.
if (os.cpus().some(cpu => cpu.model.includes('Apple')))
macVersion += '-arm64';
Ubuntu derivative mapping from `hostPlatform.ts:79-91`:
// Pop!_OS is ubuntu-based and has the same versions.
// KDE Neon is ubuntu-based and has the same versions.
// TUXEDO OS is ubuntu-based and has the same versions.
if (distroInfo?.id === 'ubuntu' || distroInfo?.id === 'pop' || distroInfo?.id === 'neon' || distroInfo?.id === 'tuxedo') {
const isUbuntu = distroInfo?.id === 'ubuntu';
const version = distroInfo?.version;
const major = parseInt(distroInfo.version, 10);
Linux architecture guard from `hostPlatform.ts:70-71`:
if (!['x64', 'arm64'].includes(os.arch()))
return { hostPlatform: '<unknown>', isOfficiallySupportedPlatform: false };
macOS Metal GPU check from `hostPlatform.ts:140-150`:
export function hasGpuMac() {
try {
if (hasGpuMacValue === undefined) {
const output = execSync('system_profiler SPDisplaysDataType', { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
hasGpuMacValue = output.includes('Metal: Supported') || output.includes('Metal Support: Metal');
}
return hasGpuMacValue;
} catch (e) {
return false;
}
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Host system is missing dependencies` | Unsupported or unrecognized Linux distribution | Set `PLAYWRIGHT_HOST_PLATFORM_OVERRIDE` to nearest supported platform |
| `<unknown>` platform detected | Non-x64/arm64 architecture on Linux | Playwright only supports x64 and arm64 on Linux |
| Browser launch failures on macOS | Missing Metal GPU support (WebKit) | Ensure GPU drivers are present; consider headless mode |
Compatibility Notes
- Ubuntu derivatives: Pop!_OS, KDE Neon, and TUXEDO OS are fully mapped to their Ubuntu base versions. Linux Mint uses a separate version mapping (Mint 20→Ubuntu 20.04, Mint 21→Ubuntu 22.04).
- Debian testing/unstable: Mapped to Debian 13 since these rolling releases do not include a numeric version in `/etc/os-release`.
- Unknown Linux distros: Fall back to `ubuntu24.04-{arch}` with `isOfficiallySupportedPlatform: false`.
- macOS beta versions: Capped at the last stable macOS major version (currently 15) to prevent unknown platform identifiers.
- Windows: Only x64 is supported (`win64`). ARM64 Windows is not officially supported.