How to Add a Custom User Agent Before Capturing a Selenium Screenshot

For Selenium with Chrome, add the custom user agent to ChromeOptions before creating the WebDriver. Then navigate to the page and save the current browser window with driver.save_screenshot(). The option applies when Chrome starts; setting it after the driver has launched is too late for that browser session.

Set a Chrome user agent and save a screenshot

Install Selenium and a compatible Chrome/ChromeDriver setup, then run this Python script. Replace the example user-agent string with the value required by your test. The value below is illustrative; it is not a claim to represent a real browser or bot.

from selenium import webdriver

user_agent = "Mozilla/5.0 (compatible; ExampleBot/1.0)"
options = webdriver.ChromeOptions()
options.add_argument(f"--user-agent={user_agent}")

driver = webdriver.Chrome(options=options)
try:
    driver.get("https://example.com")
    saved = driver.save_screenshot("screenshot.png")
    if not saved:
        raise OSError("Screenshot could not be saved")
finally:
    driver.quit()

Selenium 4 configures browser sessions through browser-specific Options classes. ChromeOptions accepts startup arguments, which is how this example passes Chrome’s --user-agent argument. See the Selenium Chrome documentation and ChromeDriver capabilities and ChromeOptions.

What the code does

1. Creates Chrome options before the browser session exists.
2. Adds the user-agent argument to Chrome’s startup configuration.
3. Starts WebDriver with those options and navigates to the URL.
4. Saves the current window to a writable PNG path.
5. Closes the driver even if navigation or screenshot saving raises an error.

save_screenshot() captures the current window and returns a boolean. Check that result so an I/O failure does not look like a successful capture. The Selenium Python API documents this behavior in its WebDriver API reference.

Choose and apply the user-agent value carefully

Use the exact string needed for the scenario you are testing. A user-agent change affects the browser’s user-agent behavior, but it does not change every part of the browser fingerprint and does not guarantee how a website will classify the session. Sites may also consider other request or browser characteristics.

• Set it before driver creation. Chrome reads the argument as part of startup configuration.
• Keep the value appropriate to the test. Do not use an unrelated string as a real-browser identity claim.
• Start a new session to change it. To test another value, create a new driver with new options.
• Use a writable PNG filename. The documented Selenium method saves the current window as a PNG.

Other Selenium language bindings

The same sequence applies in other bindings: configure the browser-specific Options object, create the session, navigate, then call the binding’s screenshot method. Selenium documents screenshot examples for Python, Java, JavaScript, C#, and Ruby in its screenshot examples. The exact option syntax varies by browser and binding, so do not assume Chrome’s command-line switch is valid for another browser.

This guide gives a runnable Chrome/Python recipe. Firefox requires Firefox-specific options and geckodriver profile configuration; verify the current Firefox user-agent preference syntax in current Selenium or Mozilla documentation before using it. The Chrome switch shown above is not a Firefox recipe.

Or skip the browser setup

If you need a screenshot from a URL rather than a Selenium-controlled browser session, ScreenshotNeo is a website screenshot API and MCP server. Its one-call GET request can return an image or PDF, with user-agent configuration available among its request options. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

These examples use the default capture settings; add the documented user-agent option when you need a specific value. 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 step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up for 1,000 free screenshots a month, with no card required.

Troubleshooting

Symptom	Likely cause	Fix
The site still appears to see the old user agent	The argument was set after the driver started, or the existing session was reused.	Add the argument before constructing the driver and start a new session.
Chrome fails to start a session	Chrome and ChromeDriver are incompatible, or the options were not passed to the driver.	Check installed versions and use matching Chrome/ChromeDriver major versions. Confirm the driver is created with options=options. See Selenium’s Chrome setup guidance.
The screenshot file is missing or empty	The path is not writable, the process is saving in a different working directory, or screenshot saving returned false.	Use a known writable path, inspect the process working directory, and check the return value of save_screenshot().
The page is not ready when the image is captured	Navigation returned before the content relevant to the screenshot appeared.	Wait for the specific page condition your test needs before saving. Avoid assuming that changing the user agent also waits for client-side content.
The target site blocks or classifies the session unexpectedly	User-agent text alone does not determine the site’s classification or full browser fingerprint.	Check the test environment and the site’s behavior; do not treat a user-agent override as a guarantee of access or identity.
Firefox rejects the Chrome option	The example uses Chrome’s startup argument mechanism.	Use Firefox-specific configuration and verify the current preference syntax in official Selenium or Mozilla documentation.

Performance, reliability, and cost

A Selenium capture starts and controls a browser session, so session startup and page loading are part of the workflow. Reuse a session when a test needs multiple captures with the same configuration; create a fresh session when changing startup options such as the user agent. Always close the driver in a finally block to release the browser process after errors.

This method uses Selenium and a local browser/driver setup; the dossier provides no benchmark or pricing figures, so none are stated here. ScreenshotNeo is an API alternative with a free tier of 1,000 shots per month and paid plans from $5 for 3,000; yearly billing gives two months free. Every feature is available on every plan.

FAQ

Can I change the user agent after calling webdriver.Chrome()?

This recipe sets it at session startup. Create a new driver session with the desired ChromeOptions value to apply a different startup configuration.

Does a custom user agent make Selenium undetectable?

No. It changes the configured user-agent behavior, but it does not alter every browser characteristic or guarantee a site’s decision.

Does Selenium save a full-page screenshot here?

The example calls save_screenshot() for the current window. Full-page capture needs a separate browser-specific approach; it is not implied by this method.