Device Pixel Ratio Policy with --bot-dpr

Display scale is part of identity

window.devicePixelRatio tells a page how many physical pixels sit behind one CSS pixel. An office laptop usually reports 1 or 1.25, a Retina MacBook reports 2, and many phones report 3. The same value feeds CSS resolution media queries, responsive image selection, and layout math, so it travels with the rest of the display identity: screen size, window size, and color depth.

When the profile describes one display and the host monitor is another, the session carries two display stories at once. BotBrowser 152.0.7977.76 adds --bot-dpr so the choice is explicit instead of being decided by whatever machine the browser runs on.

Three modes

Mode	Use when	Result
profile	The profile should define the display identity	Uses the profile display scale. Default.
real	The session should follow the host display	Uses the host display scale.
advanced	Host and profile scales cannot be aligned	Uses a compatibility fallback for that workflow.

profile is the default, so existing launches keep their current behavior. Set another mode only when the deployment needs it.

Launch

chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-dpr=profile

Switch to real when the host display is the intended environment, for example a headful workstation session that represents the operator's own monitor:

chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-dpr=real

advanced is a compatibility fallback, not a higher-accuracy mode. It keeps the profile scale with limited layout adjustment rather than rescaling the whole page. Prefer profile for profile-backed sessions and real when the host display is intentional. Use advanced only when neither fits, and keep the profile, browser version, and launch configuration fixed while you evaluate it.

Pair it with window and screen

DPR, window, and screen form one display configuration. Change them together, not one at a time between runs.

chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-dpr=profile \
  --bot-window=profile \
  --bot-screen=profile

Desktop headful sessions use host window and screen dimensions by default. If a headful session must report profile dimensions, set --bot-window=profile and --bot-screen=profile next to --bot-dpr=profile. The screen and window guide covers the size flags, and device emulation covers mobile profiles.

Per-context sessions

With per-context fingerprints, set --bot-dpr before the BrowserContext creates its first page or worker. The policy stays attached to that context's display and layout behavior for its lifetime.

const { browserContextId } = await client.send('Target.createBrowserContext', {
  botbrowserFlags: [
    '--bot-profile=/path/to/profile.enc',
    '--bot-dpr=profile'
  ]
});

Use the same mode for the main browser and a per-context profile when they represent the same device. Pick a different mode only when the context deliberately represents a different display environment. Scaling browser contexts covers the wider context lifecycle.

Validate

1. Start a session with the chosen profile and one DPR mode.
2. Keep window, screen, and DPR unchanged for the whole check.
3. Start a second session with the same profile and mode and confirm the display behavior matches.
4. When comparing modes, change only --bot-dpr and record the full launch command for each run.

Verify your browser fingerprint lists public checkers that show the reported display values.

Troubleshooting

Situation	Action
Profile display behavior expected	--bot-dpr=profile
Session must follow the host display	--bot-dpr=real
Host and profile scales cannot be aligned	--bot-dpr=advanced
Display differs between contexts	Set the mode before each context creates pages or workers
Headful dimensions follow the host	Add --bot-window=profile and --bot-screen=profile

The full flag entry is in the CLI flags reference.

Choosing a policy for a deployment

Start with the display model that the profile is meant to represent. A profile-backed browser normally carries a target operating system, viewport family, screen dimensions, and input capabilities. The display scale belongs to that same group. If the profile is used to represent a laptop or phone, profile keeps the scale connected to the rest of the profile data.

Use real for a workstation where the physical monitor is part of the user experience. This is common for a support operator, a design review, or a browser session that must follow accessibility settings on the host. In these cases the host display is the source of truth. A profile value that differs from the monitor can make text sizing and responsive layout feel unexpected, so using the real display value is clearer.

Use advanced only after testing the other two modes. It is intended for compatibility work where a host display and a profile display cannot be aligned cleanly. It keeps the profile scale while applying limited layout adjustments. It does not turn a desktop browser into a complete mobile emulator, and it does not rescale every page element. Treat it as a compatibility choice for a known workflow.

Keep related values together

Pages do not read DPR in isolation. CSS resolution queries can select a different stylesheet when the scale changes. Responsive images can select a different source. Canvas dimensions, visual viewport calculations, and application zoom controls can also depend on the relationship between CSS pixels and physical pixels.

For this reason, record the window mode, screen mode, DPR mode, viewport dimensions, and profile identifier as one launch configuration. Changing only one value makes comparisons difficult. If a test needs to compare profile and real, keep every other launch argument unchanged and run each mode in a fresh context.

Headless deployments need the same discipline even when no monitor is visible. A headless process still has a window model and a screen model. The selected DPR policy can affect layout calculations used by screenshots, PDF output, responsive application tests, and visual regression tooling. Choose the mode before creating the first page and retain it for the lifetime of the context.

Mobile and desktop considerations

Mobile profiles commonly use a larger DPR than desktop profiles. The important point is not that a larger number is better. The important point is that the value agrees with the intended device family and with the screen dimensions supplied by the same profile. Do not copy a mobile DPR into a desktop profile merely to make a page use a higher resolution image.

Desktop systems can run on monitors with different scaling settings. A host may report one value while a profile was prepared for another. profile is useful when the profile must remain stable across machines. real is useful when the current workstation must control the display. Both are valid choices with different sources of truth.

When a session moves between a local workstation and a server, decide whether the browser represents the operator's display or the profile's target display. Make that decision part of the deployment configuration. Avoid selecting a mode from an environment variable that changes silently between machines. A visible launch argument makes the resulting behavior easier to audit.

Per-context boundaries

Each browser context can represent a separate device configuration. Set the context flags before the first page or worker is created. Existing pages keep the display behavior that was established when their context started, so changing a launch command later does not retroactively update them.

If several contexts represent the same device family, use the same DPR policy and matching window and screen settings. If they intentionally represent different devices, keep each context's settings together in its own configuration record. Do not share a context between a profile-backed display and a host-backed display when the application relies on stable responsive layout.

Context pools should also record which mode was selected. This helps explain why two pages with the same URL can receive different responsive markup. It also prevents a worker from inheriting a context created for a different display policy. Close and recreate a context when the display identity must change.

Screenshots, PDFs, and visual tests

Screenshot dimensions are expressed in CSS pixels, while the output bitmap can be affected by the device scale factor. A test that compares images should keep the DPR mode fixed for both the reference capture and the current capture. Otherwise a layout can be unchanged while the bitmap dimensions or text rasterization differ.

PDF and print workflows have their own page-size rules, but the web layout that feeds the print operation still uses viewport and display calculations. Choose the DPR policy before loading the document, then keep print settings separate from display settings. This makes it easier to distinguish a CSS layout change from a paper-size change.

For visual regression, store the policy beside the viewport and browser version in the test metadata. Re-run a baseline only when the intended display policy changes. Do not update screenshots just because a runner has a different monitor. Use profile for portable baselines or real for tests explicitly tied to a workstation.

Configuration examples

The following profile-backed launch keeps display values together:

chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-dpr=profile \
  --bot-window=profile \
  --bot-screen=profile

A workstation session can instead use the host display:

chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-dpr=real \
  --bot-window=real \
  --bot-screen=real

The exact window and screen values depend on the profile and deployment. The example shows the relationship between the three policies. Select values supported by the installed BotBrowser build and keep the same set for the pages being compared.

Operational checklist

Before shipping a configuration, confirm the following in the launch record:

• the BotBrowser version is fixed;
• the profile target and host role are documented;
• the DPR mode is explicit;
• window and screen modes are explicit;
• the mode is set before the first page is created;
• screenshot or responsive tests use the same policy as their baseline;
• each per-context configuration records its own display policy;
• a change from profile to real or advanced is reviewed as a behavior change.

These checks do not require a page to expose private profile data. They make the source of display behavior clear to the team operating the browser. If a layout differs after a deployment, the launch record gives you the first places to compare.

Compatibility notes

profile remains the default for existing launches. Older command lines therefore continue to use the profile display scale unless they select another mode. The flag name is --bot-dpr; keep it alongside the other current --bot-* options in new configuration files.

When a wrapper builds command lines, pass the selected mode as a complete value rather than concatenating unvalidated text. Reject unsupported values before starting the browser. A failed launch is easier to diagnose than a session that silently falls back to a different display policy.

If a deployment supports both older and newer BotBrowser versions, keep version-specific command construction in one place. The browser version, profile format, and display policy should be reviewed together. Do not infer DPR behavior from the host operating system alone because the selected policy determines which display source is used.

Summary table

Requirement	Recommended choice
Portable profile identity	--bot-dpr=profile
Host workstation display	--bot-dpr=real
Specific compatibility case	--bot-dpr=advanced after evaluation
Stable visual baseline	Fixed mode, window, screen, and viewport
Separate device contexts	Set flags before first page or worker

The display scale policy is one part of a consistent browser configuration. Select it deliberately, keep related display values together, and record the choice with the profile and browser version.

Team handoff

A display policy is easiest to maintain when it is visible in the same place as the rest of the browser launch configuration. Include the selected mode in deployment notes, test fixtures, and runbooks. A teammate should be able to tell whether a session follows the profile or the host without opening the page and inspecting its layout.

When a configuration is handed from development to production, preserve the mode and the related window and screen settings. A local test that uses real can produce a different result on a server with no physical monitor. A production test that uses profile can produce a different result from a workstation test tied to a monitor. Neither result is inherently wrong, but the difference must be intentional.

Keep one owner for the command-line defaults used by wrappers and launch services. If several scripts each choose their own default, a maintenance change can split a context pool into different display policies. Centralizing the choice also makes a browser version upgrade easier to review. Record the old and new mode when a deployment changes it, together with any updated visual baselines.

The safest routine is simple: choose a source of truth, set the mode before page creation, keep the display values together, and compare like with like. That routine applies to local development, headful operations, headless servers, screenshots, PDFs, and per-context workloads.

Review after an upgrade

After moving to a new BotBrowser release, review the selected policy even when the command line has not changed. The default remains profile, but a release can add support for a new display combination or change the available documentation. Reuse the same profile and capture settings for a before and after comparison. If the result changes, first check the browser version, profile, window mode, screen mode, and DPR mode in that order.

For an application team, a short display policy record prevents long investigations. Store the browser release, profile family, selected mode, viewport, and capture target next to the test or service configuration. This record is useful when a page changes its responsive layout, when an image source changes, or when a screenshot is rendered at an unexpected size. It also gives reviewers a concrete list of values to approve before a rollout.

A practical rollout sequence

Begin with one representative profile and one application flow. Run the flow with profile, then repeat it with the same browser version, viewport, and window settings. If the host display is part of the requirement, repeat the comparison with real. Keep the output from each run together with the launch record. This gives the team a small reference set before the policy is applied to a larger pool.

Roll out the selected mode to one context group first. Check the pages that use responsive navigation, image selection, tables, charts, and print layouts. These areas often make display changes visible sooner than ordinary text pages. If the result is suitable, apply the same configuration to the remaining contexts that represent the same device family.

Do not mix policy changes with a browser version change, a profile migration, or a viewport redesign. Each of those changes can alter layout behavior. When several changes are needed, apply them in separate test runs and keep the records separate. A clear sequence makes it possible to identify which change affected the result.

When a service starts many contexts, set the mode in the service's shared launch configuration and copy it into each context's creation flags. Log the selected mode at startup without logging profile contents. This gives operators a useful signal during support work while keeping private configuration data out of ordinary logs.

Accessibility and user settings

Host display settings can affect text size, contrast, and input behavior in a headful workstation. If the browser is used directly by an operator, real may match that person's display expectations. If the browser is used as a portable profile-backed session, profile keeps the display behavior stable when the host changes. Discuss this choice with the people who use the session rather than selecting a mode only from server defaults.

An accessibility review should include the same viewport and window settings used in production. A page that is comfortable at one scale can become difficult to read at another scale even when the CSS viewport is unchanged. Record the selected policy with the accessibility test so later runs use the same display source.

Common configuration mistakes

The most common mistake is leaving the mode implicit while changing the host machine. Existing launches use profile by default, but a wrapper or deployment script may add window or screen arguments separately. Write all three policies explicitly when a workflow depends on a particular display identity.

Another mistake is changing DPR after a context has already created pages. Create a new context for a new display policy. A new context also gives screenshot and responsive tests a clean starting point, which avoids carrying state from the previous display configuration.

Finally, avoid using advanced as a general quality setting. It is a compatibility option for a specific need. Start with profile or real, document why they do not fit, and keep the advanced configuration limited to the workflow that requires it.