Registry / http-networking / ua-generator

ua-generator

JSON →
library2.1.1pypypi✓ verified 86d ago

ua-generator is a lightweight Python library designed to generate realistic, random user-agent strings. It supports Python >= 3.9 and operates without external dependencies or the need for external user-agent lists, as its user-agent and platform versions are hardcoded and based on real release data. The library also includes support for Client Hints (Sec-CH-UA fields). It maintains a regular release cadence, primarily for version updates to keep its internal data current, with the latest version being 2.0.25.

pip install ua-generator
INSTALL
IMPORT
SIG · UA-GENERATOR
U
ua-generator
http-networkingpythonv2.1.1
Install
1.7s avg
Import
30ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.032s · 18.1MB
glibc
py 3.103.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.
fix
Run `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.
fix
Instead 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.
fix
Install 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.
fix
Call 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()`.
fix
Use 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()`.
fix
Use 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.

Agent activity
17 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources