How to Override the User-Agent for One Site

Last updated 2026-08-05

Overriding the User-Agent is how you check whether a server is doing something different for mobile clients, get past a crude browser sniff, or reproduce a bug reported by someone on another platform. Doing it for one domain rather than globally is what keeps the rest of your browsing normal.

The rule

Match:  domain is example.com
Action: set request header  User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_0
        like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0
        Mobile/15E148 Safari/604.1

Copy a real User-Agent string rather than inventing one. Servers and analytics parse these with strict regular expressions, and a malformed string produces behavior that matches no real device, which is worse than not testing at all. User-Agent is one of the request headers Chrome allows you to append to, though set is what you almost always want.

The header is only half the story

This is where most people get stuck. A header rule changes what the server receives. It does not change what JavaScript on the page reads:

Surface	Changed by a header rule?	What reads it
`User-Agent` request header	yes	server-side code, logs, analytics, CDNs
`navigator.userAgent`	no	client-side feature detection and browser sniffs
`navigator.userAgentData` and `Sec-CH-UA` headers	the headers can be set, the JavaScript object cannot	modern client hints code
Viewport, touch events, device pixel ratio	no	responsive layout and touch handling

Server-side rendering or redirects: a header rule is exactly the right tool. The server is the thing being fooled.
Client-side sniffing: a header rule changes nothing, because the page reads navigator.userAgent. Use DevTools device mode, which overrides both the header and the JavaScript value for that tab.
Layout and touch behavior: device mode again. No header makes your desktop report a touchscreen.

Chrome has been freezing and reducing the User-Agent string for years, moving detail into User-Agent Client Hints (Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform). If a server ignores your override, check whether it is reading client hints instead. Those are ordinary request headers, so the same rule mechanism applies.

Useful variations

Test how your site treats crawlers: set a Googlebot User-Agent against your own staging host to check for cloaking or accidental blocks. Do this on your own property only.
Reproduce an old-browser bug: combine an old User-Agent with a narrow domain match, then watch which polyfills and warning banners the server decides to send.
Check your analytics pipeline: a known-unusual User-Agent on a staging domain tells you quickly whether events are bucketed the way you expect.
Remove it entirely: a remove rule shows how a service behaves with no User-Agent at all, which is a real case for API clients and a common source of 403s.

Verify it worked

DevTools, Network, select the document request, and read Request Headers.
Or hit an echo service and read the response body, which shows what the server actually received.
Compare with curl -A to confirm the server, not the browser, is what changed.

curl -A 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)' \
  -s https://example.com | head -40

Common questions

Why does the site still detect my real browser?

Almost certainly because the detection runs in JavaScript, reading navigator.userAgent, which a header rule cannot change. Use DevTools device mode when you need both the header and the JavaScript value to agree, and a header rule when the server is what you are testing.

Can I change the User-Agent for every site at once?

You can, with a wildcard match, but it is a bad default. A global override skews analytics on every site you visit and can trigger odd behavior on sites that adapt to the string. Match the one domain you are testing.

What is the difference from DevTools device mode?

Device mode overrides the User-Agent header, navigator.userAgent, client hints, the viewport, and touch emulation for that tab, and it stops when you close DevTools. A header rule changes only the header, applies to every tab that matches, and persists until you turn it off. They suit different jobs.

Does overriding the User-Agent violate a site’s terms?

It can. Sending a false User-Agent to bypass access controls or scrape a service is a terms-of-service question, not a technical one, and it is on you. On your own sites and staging environments, this is a routine debugging technique.