Playwright CLI Retina Screenshots

playwright-retina.md

Taking Retina (2x) Screenshots with Playwright CLI

By default, @playwright/cli captures screenshots at 1x resolution — even on HiDPI/Retina displays. This results in blurry images compared to native screenshots.

Here's how to get crisp, high-resolution screenshots.

The Problem

Playwright CLI creates browser contexts with deviceScaleFactor: 1 by default, and its built-in screenshot command uses scale: 'css'. This means:

• The page renders at 1x pixel density
• Screenshots are captured at CSS resolution (e.g. 1920×1080)
• Text and icons appear blurry when viewed on Retina displays

The Solution

You need two things:

1. Set deviceScaleFactor: 2 via a config file

Create .playwright/cli.config.json:

{
  "browser": {
    "contextOptions": {
      "viewport": { "width": 1920, "height": 1080 },
      "deviceScaleFactor": 2
    }
  }
}

Important: You must include viewport — Playwright throws an error if deviceScaleFactor is set with null viewport (which is the default).

2. Use run-code with scale: 'device' for screenshots

The built-in screenshot command hardcodes scale: 'css', which discards the extra resolution even when DPR is 2. Use run-code instead:

playwright-cli run-code 'async (page) => {
  await page.screenshot({
    path: "screenshot.png",
    scale: "device",
    type: "png"
  });
}'

Full Example

# Open browser with the 2x config
playwright-cli open https://example.com --headed --config .playwright/cli.config.json

# Navigate to the page
playwright-cli goto "https://example.com/my-page"

# Take a Retina screenshot (3840×2160 for a 1920×1080 viewport)
playwright-cli run-code 'async (page) => {
  await page.screenshot({
    path: "my-page.png",
    scale: "device",
    type: "png"
  });
}'

# Close
playwright-cli close

Comparison

Method	Dimensions	Quality
Default (screenshot command, no config)	1920×1080	1x — blurry on Retina
Config with DPR 2 + screenshot command	1920×1080	Still 1x — scale: 'css' discards 2x pixels
Config with DPR 2 + run-code with scale: 'device'	3840×2160	2x — crisp on Retina

Why Both Pieces Are Needed

• deviceScaleFactor: 2 in config → tells the browser to render at 2x pixel density (fonts, icons, everything is rendered with double the pixels)
• scale: 'device' in screenshot → captures the full device pixels instead of downscaling back to CSS dimensions

Without the config, scale: 'device' has no effect because DPR is already 1. Without scale: 'device', the screenshot is downscaled from 2x back to 1x (1920×1080).

Notes

• Tested with @playwright/cli v0.1.0 (built on Playwright MCP)
• The config file format follows the Playwright MCP server config schema
• File sizes roughly double (~300KB → ~700KB for a typical full-page screenshot)
• Works with --headed and headless modes