Introduction

If you want to send a custom User-Agent with Python requests, the mechanism is simply an HTTP header. The practical question is whether you want to set it for one request or reuse it across many requests through a session.

Set User-Agent on One Request

The simplest pattern is to pass a headers dictionary.

1import requests
2
3headers = {
4    "User-Agent": "my-app/1.0"
5}
6
7response = requests.get("https://httpbin.org/headers", headers=headers, timeout=10)
8print(response.status_code)
9print(response.text)

That sends the User-Agent only for that one call.

Reuse the Header Across Many Requests

If your code makes multiple requests, a Session is cleaner.

1import requests
2
3session = requests.Session()
4session.headers.update({
5    "User-Agent": "my-app/1.0"
6})
7
8response = session.get("https://httpbin.org/headers", timeout=10)
9print(response.status_code)

This avoids repeating the same header dictionary in every request.

Why User-Agent Matters

Servers often log, filter, or route traffic based on User-Agent. Some APIs require a descriptive agent string for identification, and many debugging tasks are easier when requests carry a recognizable client name rather than a default library signature.

A clear application-specific string is usually better than pretending to be a random browser.

Add More Context If Needed

You can include version and contact or environment information when appropriate.

headers = {
    "User-Agent": "my-app/1.2 (+https://example.com/support)"
}

That makes server-side logs easier to understand and gives operators a way to identify your client behavior.

Override or Merge Carefully

If you pass headers directly to a request while also using a session, request-level headers override or supplement session defaults for that specific call.

1response = session.get(
2    "https://httpbin.org/headers",
3    headers={"User-Agent": "my-app/2.0-debug"},
4    timeout=10,
5)

This is useful for temporary diagnostics or endpoint-specific overrides.

Timeouts Still Matter

Even though the topic is headers, good request hygiene still matters. Include timeouts and handle failures explicitly.

1import requests
2
3try:
4    response = requests.get(
5        "https://example.com",
6        headers={"User-Agent": "my-app/1.0"},
7        timeout=5,
8    )
9    response.raise_for_status()
10except requests.RequestException as exc:
11    print(f"request failed: {exc}")

That is better than debugging silent hangs while focusing only on headers.

Common Pitfalls

Verify What You Actually Sent

When debugging headers, it helps to hit an inspection endpoint rather than guessing from client code alone. Services such as httpbin can reflect the headers back so you can confirm whether your session defaults, request-level overrides, proxies, or middleware changed the final request before it reached the server.

1import requests
2
3response = requests.get(
4    "https://httpbin.org/headers",
5    headers={"User-Agent": "my-app/1.0"},
6    timeout=10,
7)
8print(response.json())

Sessions, Bots, and Scrapers

In scraping or automation code, the User-Agent header is only one part of the request identity. Servers may also care about cookies, authentication, accepted content types, and request pacing. Setting User-Agent helps, but it does not turn an otherwise invalid client into a browser-equivalent session.

The most common mistake is using the wrong header name casing or spelling. The standard name is User-Agent.

Another mistake is rebuilding the same headers dictionary over and over when a Session default would be clearer.

Developers also sometimes copy a browser User-Agent string unnecessarily when a descriptive application identifier would be more honest and easier to maintain. A stable application-specific identifier also makes server-side monitoring much easier over time. It also makes rate-limit discussions with API providers much clearer.

Summary

• Send a custom User-Agent by passing the User-Agent header.
• Use request-level headers for one-off calls.
• Use a requests.Session to reuse the header across many requests.
• Keep the agent string descriptive and intentional.
• Combine header usage with timeouts and normal error handling.