Set the Browser User Agent with Puppeteer

Set a Puppeteer page’s user agent with page.setUserAgent(), and await it before navigating or doing other work that depends on the override:

await page.setUserAgent({ userAgent: 'your user-agent string' });

The current API accepts an options object. Alongside userAgent, you can provide optional userAgentMetadata and platform. This is a page-level setting: it does not change the browser’s original user agent or, by itself, reproduce every characteristic of a device. See the Puppeteer Page.setUserAgent API.

Set a user agent in a complete Puppeteer script

Install Puppeteer, save this as user-agent.mjs, and run it with Node.js. Replace the placeholder with a user-agent string appropriate for the browser and scenario you intend to represent. The official references do not supply a universally suitable current string, so avoid treating an arbitrary version string as authoritative.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();

  await page.setUserAgent({
    userAgent: 'your user-agent string',
  });

  await page.goto('https://example.com', {
    waitUntil: 'domcontentloaded',
  });

  console.log('Page title:', await page.title());
} finally {
  await browser.close();
}

The order matters: set the override before page.goto() so the initial navigation uses it. Awaiting the call ensures the setting is applied before the next step. The finally block closes the browser even if navigation or page work throws an error.

Install the package that fits your browser setup

puppeteer downloads a compatible Chrome version as part of installation.
puppeteer-core does not download Chrome. Use it when connecting to a remote browser or when you manage browser binaries separately.

That choice affects browser installation and management, not the page-level user-agent API. Follow the Puppeteer installation guide for the package and browser setup that match your environment.

Choose between a user-agent override and device emulation

Approach	What it configures	Use it when
`page.setUserAgent()`	A user-agent string, with optional metadata and platform fields.	Your task specifically requires changing the page’s user-agent settings.
`page.emulate(device)`	A known device profile’s user agent and viewport.	You need a device profile, including its viewport behavior.

To emulate a known device, import it from Puppeteer’s device definitions and apply the profile before navigation:

import puppeteer from 'puppeteer';
import { KnownDevices } from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  const device = KnownDevices['iPhone 13'];

  await page.emulate(device);
  await page.goto('https://example.com');

  console.log('Page title:', await page.title());
} finally {
  await browser.close();
}

Choose a device name available in the installed version’s KnownDevices reference. Puppeteer recommends emulating before navigation: changing the viewport can affect the page and may trigger a reload in some cases. Device emulation is a shortcut for setting both user agent and viewport; a user-agent string alone should not be described as a complete device simulation. See the Page.emulate API and emulation guide.

Read the browser’s original user agent

browser.userAgent() reports the browser’s original user agent. It does not read back the page’s override. Keep the distinction in mind when inspecting or logging values:

const originalUserAgent = await browser.userAgent();
console.log('Browser user agent:', originalUserAgent);

The override is set on a page, so apply it to every page that needs it. Creating another page does not make the setting browser-wide. The Browser.userAgent API documents the browser-level value.

Options and practical choices

userAgent: the string to use for the page. Choose it to match the scenario you are testing. Do not copy an old browser version from an example without checking whether it remains appropriate.
userAgentMetadata: optional metadata supported by the documented options form. Provide it only when your use case requires metadata alongside the string.
platform: an optional platform value. Use it when the page’s user-agent settings need to represent a particular platform.

The API reference defines these fields, but the reviewed documentation does not establish a universally correct metadata or platform configuration. Check the API documentation for your installed Puppeteer version when setting them.

Use a deliberate user-agent value for reproducible testing, and keep it aligned with the browser or scenario being represented. A changed user agent is not proof that the page behaves exactly as it would on another physical device or browser.

Or skip the browser setup

If your goal is a screenshot rather than browser automation, ScreenshotNeo takes a screenshot with one GET request. Its API can return PNG, JPEG, WebP, or PDF, and supports a custom user agent along with viewport, device presets, cookies, headers, and other capture options. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com \
  -d user_agent='your user-agent string' \
  -o shot.webp

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Troubleshooting

Symptom	Likely cause	Fix
The first request still uses the old value.	The page navigated before the override was applied, or the call was not awaited.	Call and await `page.setUserAgent()` before `page.goto()`.
A new page uses the default user agent.	The override was set on a different page.	Apply the setting to each page that needs it, or use a shared page setup function.
The result does not look like the target device.	A user-agent override changes user-agent settings, not necessarily viewport and other device characteristics.	Use `page.emulate(device)` for a known device profile, and do so before navigation.
`KnownDevices` cannot find the chosen device.	The name is not present in the installed Puppeteer version’s device list.	Check the installed version’s KnownDevices reference and use an available profile.
The browser executable is missing.	`puppeteer-core` does not download Chrome, or the configured browser binary is unavailable.	Install/manage a compatible browser or use the package and setup described in the installation guide.
The method signature in an older example does not work.	Puppeteer API signatures have changed across versions.	Use the options-object form documented for your installed version and check its API reference before updating.

Performance, reliability, and cost

Setting a page’s user agent is a page configuration call that returns a promise; await it before dependent navigation or page work. The supplied references do not give a measurable performance impact, so no timing claim is made. Reliability depends on using the API signature supported by the installed version, applying the setting to the right page, and choosing a value appropriate to the scenario. Puppeteer’s package choice affects whether Chrome is downloaded or managed separately, which changes setup requirements. No usage price is specified in the reviewed Puppeteer references.

FAQ

Does setting a user agent change every page in the browser?

No. It is set on a Puppeteer page. Apply it to each page that needs the override.

Should I use a made-up user-agent string?

Use a value that fits the browser and scenario you intend to represent. The reviewed documentation does not provide a universal current string.

Does a user-agent override emulate a phone?

Not by itself. Use page.emulate(device) when you need a known device profile and viewport as well as the user agent.

Can I use this with a remote browser?

Yes, the setting is a page API. Puppeteer’s installation guide describes puppeteer-core for remote browser connections or separately managed browser binaries; browser connection setup is independent of the user-agent call.