Install & Compatibility
Where this runs
tested against v2.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.032s · 18.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.028s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
generate
✓ import ua_generator
ua = ua_generator.generate()
The primary function `generate` is directly accessible after importing the `ua_generator` module.
This quickstart demonstrates basic user-agent generation and more advanced customization using browser and device criteria. It also shows how to retrieve a dictionary of HTTP headers, including Client Hints, which can be directly used with HTTP libraries like `requests` for more comprehensive browser emulation. The `ua.text` property provides just the User-Agent string, while `ua.headers.get()` provides a full set of relevant HTTP headers.
import ua_generator
import requests
# Basic usage: generate a random user agent
def get_random_ua_text():
ua = ua_generator.generate()
print(f"Generated User-Agent Text: {ua.text}")
return ua.text
# Advanced usage: generate with specific criteria and get full headers including Client Hints
def get_custom_ua_headers(browser_list=None, device_list=None):
browser_list = browser_list or ['chrome', 'firefox']
device_list = device_list or ['desktop', 'mobile']
ua = ua_generator.generate(browser=browser_list, device=device_list)
print(f"Generated User-Agent Text (custom): {ua.text}")
# Use ua.headers.get() for a dictionary of HTTP headers, including Client Hints
headers = ua.headers.get()
print(f"Generated HTTP Headers: {headers}")
# Example of using with requests (simulating HTTP request)
try:
response = requests.get('https://httpbin.org/headers', headers=headers)
response.raise_for_status() # Raise an exception for HTTP errors
print(f"Requests response (status {response.status_code}): {response.json()['headers']}")
except requests.exceptions.RequestException as e:
print(f"Error making request: {e}")
return headers
if __name__ == '__main__':
get_random_ua_text()
print("\n---\n")
get_custom_ua_headers(browser_list=['edge'], device_list=['desktop'])
print("\n---\n")
get_custom_ua_headers(browser_list=['safari', 'firefox'], device_list=['mobile'])
Debug
Known issues
gotchaUser-agent strings become outdated over time. To ensure the generated user-agents remain realistic and effective for modern web interactions, it is crucial to periodically upgrade the `ua-generator` library.fixRun `pip install -U ua-generator` regularly to update to the latest version, which includes updated user-agent data. Consider automating this check in your development or deployment pipeline.
affects: All versions
gotchaFor comprehensive browser emulation, especially in environments like Selenium or when interacting with services that utilize User-Agent Client Hints, relying solely on the `ua.text` string may be insufficient. Modern browsers transmit additional `Sec-CH-UA` headers.fixInstead of `ua.text`, use `ua.headers.get()` to retrieve a dictionary of all relevant HTTP headers, including Client Hints. This dictionary can be passed directly to HTTP client libraries (e.g., `requests`, `httpx`) or used to configure browser automation tools (e.g., `selenium` with CDP commands) for a more complete and accurate user-agent profile. Version 2.0.17 introduced `ua.navigator.get()` specifically for Selenium's `NavigatorUAData` fields.
affects: All versions prior to 2.0.17, and users of 2.0.17+ who only use `ua.text`.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ua_generator'
The 'ua-generator' package is not installed in your Python environment, or there is a typo in the import statement.
fixInstall the package using pip: `pip install ua-generator`. Ensure your import statement is `import ua_generator`.
AttributeError: 'function' object has no attribute 'random'
You are trying to access the `.random` attribute on the `generate` function itself, rather than on the `UserAgent` object returned by calling the function.
fixCall the `generate` function by adding parentheses: `ua = ua_generator.generate()`, then access `ua.random`.
ValueError: Invalid platform: 'Mac OS'
An unsupported or incorrectly cased/formatted string was passed as the `platform` argument to `ua_generator.generate()`.
fixUse one of the supported platform names, which are typically lowercase (e.g., `'windows'`, `'macos'`, `'linux'`, `'android'`, `'ios'`).
TypeError: generate() got an unexpected keyword argument 'os'
An incorrect keyword argument ('os') was used instead of the correct one ('platform') when calling `ua_generator.generate()`.
fixUse the correct keyword argument `platform`: `ua = ua_generator.generate(platform='windows')`.
Upgrade
Version history
2.1.1latest on PyPI · released May 24, 2026
Audit
Dependencies
No dependency data recorded yet.