# ua-generator
A random user-agent generator for Python >= 3.9
# Features
- No dependency.
- No external user-agent list, no downloads.
- User-agent versions are hardcoded into the code.
- Platform and browser versions are based on real releases.
- Client Hints (Sec-CH-UA fields).
- Easy to integrate into HTTP libraries.
# Install & upgrade
```bash
pip install -U ua-generator
```
_Note: Upgrade ua-generator periodically to keep user-agent versions up to date._
# Basic usage
```python
import ua_generator
ua = ua_generator.generate()
print(ua) # Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/15.2 Safari/604.1.38
```
# Customization
**It takes three different parameters to customize the user-agent.**
```python
device = ['desktop', 'mobile']
platform = ['windows', 'macos', 'ios', 'linux', 'android']
browser = ['chrome', 'edge', 'firefox', 'safari']
```
_Note: All parameters are optional and multiple types can be specified using a list (or tuple)._
## Customized user-agent generation:
```python
import ua_generator
# Example 1:
ua = ua_generator.generate(device='desktop', browser=['chrome', 'edge'])
print(ua.text) # Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.5359.145 Safari/537.36
print(ua.platform) # windows
print(ua.browser) # chrome
print(ua.ch.brands) # "Not A(Brand";v="99", "Chromium";v="108", "Google Chrome";v="108"
print(ua.ch.mobile) # ?0
print(ua.ch.platform) # "Windows"
print(ua.ch.platform_version) # "13.0.0"
print(ua.ch.bitness) # "64"
print(ua.ch.architecture) # "x86"
# Example 2:
ua = ua_generator.generate(platform=['ios', 'macos'], browser='chrome')
print(ua.text) # Mozilla/5.0 (iPhone; CPU iPhone OS 17_0_2 like Mac OS X) AppleWebKit/537.36 (KHTML, like Gecko) CriOS/119.0.6045.176 Mobile/15E148 Safari/537.36
print(ua.platform) # ios
print(ua.browser) # chrome
print(ua.ch.brands) # "Not A(Brand";v="99", "Chromium";v="119", "Google Chrome";v="119"
print(ua.ch.mobile) # ?1
print(ua.ch.platform) # "iOS"
print(ua.ch.platform_version) # "17.0.2"
print(ua.ch.bitness) # "64"
print(ua.ch.architecture) # "arm"
```
# Headers
```python
ua = ua_generator.generate(browser=['chrome', 'edge'])
# This will return a dictionary containing the generated user-agent:
print(ua.headers.get())
{
'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.43 Safari/537.36',
'sec-ch-ua': '"Not A(Brand";v="99", "Chromium";v="103", "Google Chrome";v="103"',
'sec-ch-ua-mobile': '?0',
'sec-ch-ua-platform': '"macOS"'
}
# Extending the "Client Hints" by a value of the "Accept-CH" header:
ua.headers.accept_ch('Sec-CH-UA-Platform-Version, Sec-CH-UA-Full-Version-List')
print(ua.headers.get())
{
'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.6261.94 Safari/537.36',
'sec-ch-ua': '"Not A(Brand";v="99", "Chromium";v="122", "Google Chrome";v="122"',
'sec-ch-ua-mobile': '?0',
'sec-ch-ua-platform': '"macOS"',
'sec-ch-ua-platform-version': '"14.1.0"',
'sec-ch-ua-full-version-list': '"Not A(Brand";v="99.0.0.0", "Chromium";v="122.0.6261.94", "Google Chrome";v="122.0.6261.94"'
}
```
## Integrating into the [requests](https://pypi.org/project/requests/):
```python
import requests
import ua_generator
ua = ua_generator.generate(browser=['chrome', 'edge'])
r = requests.get('https://httpbin.org/get', headers=ua.headers.get())
# or, usage with requests.Session():
ua = ua_generator.generate(browser=['chrome', 'edge'])
s = requests.Session()
s.headers.update(ua.headers.get())
r = s.get('https://httpbin.org/get')
```
## Integrating into the [httpx](https://pypi.org/project/httpx/):
```python
import httpx
import ua_generator
ua = ua_generator.generate(browser=['chrome', 'edge'])
r = httpx.get('https://httpbin.org/get', headers=ua.headers.get())
# or, usage with httpx.Client():
ua = ua_generator.generate(browser=['chrome', 'edge'])
c = httpx.Client(headers=ua.headers.get())
r = c.get('https://httpbin.org/get')
```
## Integrating into the [urllib](https://docs.python.org/3/library/urllib.request.html):
```python
import urllib.request
import ua_generator
ua = ua_generator.generate(browser=['chrome', 'edge'])
request = urllib.request.Request('https://httpbin.org/get', headers=ua.headers.get())
handler = urllib.request.urlopen(request)
response = handler.read().decode('utf-8')
```
# Options
You can define options using the "options" parameter for further customization.
## weighted_versions
To increase the probability of the latest versions being chosen. Default is `False`.
```python
import ua_generator
from ua_generator.options import Options
# Enabling weighted versions
options = Options()
options.weighted_versions = True
ua = ua_generator.generate(browser=['chrome', 'edge'], options=options)
```
## version_ranges
To choose only versions within specified ranges. Default is `None`.
```python
import ua_generator
from ua_generator.options import Options
from ua_generator.data.version import VersionRange
# Choosing only versions within specified ranges
options = Options()
options.version_ranges = {
'chrome': VersionRange(125, 129), # Choose version between 125 and 129
'edge': VersionRange(min_version=120), # Choose version 120 minimum
}
ua = ua_generator.generate(browser='chrome', options=options)
```
_Note: If there is no valid version within the range you set, the filter will just skip it and return a random valid version instead._
# Issues
You can create an issue [from here](https://github.com/iamdual/ua-generator/issues) if you are experiencing a problem.
# Contributing
Pull requests are welcome. Don't forget to run tests.
# Contributors
Ekin Karadeniz ([@iamdual](https://github.com/iamdual)) and [the GitHub community](https://github.com/iamdual/ua-generator/graphs/contributors).
Raw data
{
"_id": null,
"home_page": "https://github.com/iamdual/ua-generator",
"name": "ua-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Ekin Karadeniz",
"author_email": "iamdual@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/b1/b9/4cf7241277a3ee7a173acbe5283c5c8614158879a968f1022270f360bcfb/ua_generator-2.0.12.tar.gz",
"platform": null,
"description": "# ua-generator\n\nA random user-agent generator for Python >= 3.9\n\n# Features\n\n- No dependency.\n- No external user-agent list, no downloads.\n- User-agent versions are hardcoded into the code.\n- Platform and browser versions are based on real releases.\n- Client Hints (Sec-CH-UA fields).\n- Easy to integrate into HTTP libraries.\n\n# Install & upgrade\n\n```bash\npip install -U ua-generator\n```\n_Note: Upgrade ua-generator periodically to keep user-agent versions up to date._\n\n# Basic usage\n\n```python\nimport ua_generator\n\nua = ua_generator.generate()\nprint(ua) # Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/15.2 Safari/604.1.38\n```\n\n# Customization\n\n**It takes three different parameters to customize the user-agent.**\n\n```python\ndevice = ['desktop', 'mobile']\nplatform = ['windows', 'macos', 'ios', 'linux', 'android']\nbrowser = ['chrome', 'edge', 'firefox', 'safari']\n```\n_Note: All parameters are optional and multiple types can be specified using a list (or tuple)._\n## Customized user-agent generation:\n\n```python\nimport ua_generator\n\n# Example 1:\nua = ua_generator.generate(device='desktop', browser=['chrome', 'edge'])\nprint(ua.text) # Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.5359.145 Safari/537.36\nprint(ua.platform) # windows\nprint(ua.browser) # chrome\nprint(ua.ch.brands) # \"Not A(Brand\";v=\"99\", \"Chromium\";v=\"108\", \"Google Chrome\";v=\"108\"\nprint(ua.ch.mobile) # ?0\nprint(ua.ch.platform) # \"Windows\"\nprint(ua.ch.platform_version) # \"13.0.0\"\nprint(ua.ch.bitness) # \"64\"\nprint(ua.ch.architecture) # \"x86\"\n\n# Example 2:\nua = ua_generator.generate(platform=['ios', 'macos'], browser='chrome')\nprint(ua.text) # Mozilla/5.0 (iPhone; CPU iPhone OS 17_0_2 like Mac OS X) AppleWebKit/537.36 (KHTML, like Gecko) CriOS/119.0.6045.176 Mobile/15E148 Safari/537.36\nprint(ua.platform) # ios\nprint(ua.browser) # chrome\nprint(ua.ch.brands) # \"Not A(Brand\";v=\"99\", \"Chromium\";v=\"119\", \"Google Chrome\";v=\"119\"\nprint(ua.ch.mobile) # ?1\nprint(ua.ch.platform) # \"iOS\"\nprint(ua.ch.platform_version) # \"17.0.2\"\nprint(ua.ch.bitness) # \"64\"\nprint(ua.ch.architecture) # \"arm\"\n```\n\n# Headers\n\n```python\nua = ua_generator.generate(browser=['chrome', 'edge'])\n\n# This will return a dictionary containing the generated user-agent:\nprint(ua.headers.get())\n{\n 'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.5060.43 Safari/537.36',\n 'sec-ch-ua': '\"Not A(Brand\";v=\"99\", \"Chromium\";v=\"103\", \"Google Chrome\";v=\"103\"',\n 'sec-ch-ua-mobile': '?0',\n 'sec-ch-ua-platform': '\"macOS\"'\n}\n\n# Extending the \"Client Hints\" by a value of the \"Accept-CH\" header:\nua.headers.accept_ch('Sec-CH-UA-Platform-Version, Sec-CH-UA-Full-Version-List')\nprint(ua.headers.get())\n{\n 'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.6261.94 Safari/537.36',\n 'sec-ch-ua': '\"Not A(Brand\";v=\"99\", \"Chromium\";v=\"122\", \"Google Chrome\";v=\"122\"',\n 'sec-ch-ua-mobile': '?0',\n 'sec-ch-ua-platform': '\"macOS\"',\n 'sec-ch-ua-platform-version': '\"14.1.0\"',\n 'sec-ch-ua-full-version-list': '\"Not A(Brand\";v=\"99.0.0.0\", \"Chromium\";v=\"122.0.6261.94\", \"Google Chrome\";v=\"122.0.6261.94\"'\n}\n```\n\n## Integrating into the [requests](https://pypi.org/project/requests/):\n\n```python\nimport requests\nimport ua_generator\n\nua = ua_generator.generate(browser=['chrome', 'edge'])\nr = requests.get('https://httpbin.org/get', headers=ua.headers.get())\n\n\n# or, usage with requests.Session():\nua = ua_generator.generate(browser=['chrome', 'edge'])\ns = requests.Session()\ns.headers.update(ua.headers.get())\nr = s.get('https://httpbin.org/get')\n```\n\n## Integrating into the [httpx](https://pypi.org/project/httpx/):\n\n```python\nimport httpx\nimport ua_generator\n\nua = ua_generator.generate(browser=['chrome', 'edge'])\nr = httpx.get('https://httpbin.org/get', headers=ua.headers.get())\n\n\n# or, usage with httpx.Client():\nua = ua_generator.generate(browser=['chrome', 'edge'])\nc = httpx.Client(headers=ua.headers.get())\nr = c.get('https://httpbin.org/get')\n```\n\n## Integrating into the [urllib](https://docs.python.org/3/library/urllib.request.html):\n\n```python\nimport urllib.request\nimport ua_generator\n\nua = ua_generator.generate(browser=['chrome', 'edge'])\nrequest = urllib.request.Request('https://httpbin.org/get', headers=ua.headers.get())\nhandler = urllib.request.urlopen(request)\nresponse = handler.read().decode('utf-8')\n```\n\n# Options\n\nYou can define options using the \"options\" parameter for further customization.\n\n## weighted_versions\nTo increase the probability of the latest versions being chosen. Default is `False`.\n\n```python\nimport ua_generator\nfrom ua_generator.options import Options\n\n# Enabling weighted versions\noptions = Options()\noptions.weighted_versions = True\nua = ua_generator.generate(browser=['chrome', 'edge'], options=options)\n```\n\n## version_ranges\nTo choose only versions within specified ranges. Default is `None`.\n\n```python\nimport ua_generator\nfrom ua_generator.options import Options\nfrom ua_generator.data.version import VersionRange\n\n# Choosing only versions within specified ranges\noptions = Options()\noptions.version_ranges = {\n 'chrome': VersionRange(125, 129), # Choose version between 125 and 129\n 'edge': VersionRange(min_version=120), # Choose version 120 minimum\n}\nua = ua_generator.generate(browser='chrome', options=options)\n```\n\n_Note: If there is no valid version within the range you set, the filter will just skip it and return a random valid version instead._\n\n# Issues\n\nYou can create an issue [from here](https://github.com/iamdual/ua-generator/issues) if you are experiencing a problem.\n\n# Contributing\n\nPull requests are welcome. Don't forget to run tests.\n\n# Contributors\n\nEkin Karadeniz ([@iamdual](https://github.com/iamdual)) and [the GitHub community](https://github.com/iamdual/ua-generator/graphs/contributors).\n",
"bugtrack_url": null,
"license": null,
"summary": "A random user-agent generator",
"version": "2.0.12",
"project_urls": {
"Bug Tracker": "https://github.com/iamdual/ua-generator/issues",
"Homepage": "https://github.com/iamdual/ua-generator"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "014f95302115c059db41daa3836cf8d8ac6bf90c52fdb70d9d138cd119f0f387",
"md5": "f56c3109db6ad53148138853b0d634f5",
"sha256": "5af769c099a71d8e476c6fb3926cd6bc64e1427af24f6945aea38bc576f4fb1a"
},
"downloads": -1,
"filename": "ua_generator-2.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f56c3109db6ad53148138853b0d634f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 30711,
"upload_time": "2025-08-31T06:12:42",
"upload_time_iso_8601": "2025-08-31T06:12:42.242305Z",
"url": "https://files.pythonhosted.org/packages/01/4f/95302115c059db41daa3836cf8d8ac6bf90c52fdb70d9d138cd119f0f387/ua_generator-2.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1b94cf7241277a3ee7a173acbe5283c5c8614158879a968f1022270f360bcfb",
"md5": "c75e05da927a17e45363c472addfc02b",
"sha256": "8a7ee803d765e05e6ca5cea16b4e70c56e194c7103cbcc300ce63bea58faef92"
},
"downloads": -1,
"filename": "ua_generator-2.0.12.tar.gz",
"has_sig": false,
"md5_digest": "c75e05da927a17e45363c472addfc02b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 26398,
"upload_time": "2025-08-31T06:12:43",
"upload_time_iso_8601": "2025-08-31T06:12:43.778276Z",
"url": "https://files.pythonhosted.org/packages/b1/b9/4cf7241277a3ee7a173acbe5283c5c8614158879a968f1022270f360bcfb/ua_generator-2.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 06:12:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iamdual",
"github_project": "ua-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ua-generator"
}
JSON
