fake-useragent

Up-to-date simple useragent faker with real world database.

Features

Data is pre-downloaded & post-processed from Intoli LLC and the data is part of the package itself
The data consists of a wide range of browser agents and various browsers
Retrieves user-agent strings (both of type: desktop, tablet and/or mobile UAs)
Retrieve user-agent Python dictionary (aka object), with fields like useragent, percent, type, device_brand, browser, browser_version, os, os_version and platform
Supports Python 3.x

Installation

pip install fake-useragent

Or if you have multiple Python / pip versions installed, use pip3:

pip3 install fake-useragent

Usage

Simple usage examples below, see also next chapters in this readme for more advanced usages:

from fake_useragent import UserAgent
ua = UserAgent()

# Get a random browser user-agent string
print(ua.random)
# Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:132.0) Gecko/20100101 Firefox/132.0

# Or get user-agent string from a specific browser
print(ua.chrome)
# Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36
print(ua.google)
# Mozilla/5.0 (iPhone; CPU iPhone OS 18_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) GSA/343.0.695551749 Mobile/15E148 Safari/604.1
print(ua['Chrome'])
# Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36
print(ua.firefox)
# Mozilla/5.0 (Android 14; Mobile; rv:133.0) Gecko/133.0 Firefox/133.0
print(ua.ff)
# Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:132.0) Gecko/20100101 Firefox/132.0
print(ua.safari)
# Mozilla/5.0 (iPhone; CPU iPhone OS 17_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.6 Mobile/15E148 Safari/604.1 Ddg/17.6
print(ua.opera)
# Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36 OPR/114.0.0.0
print(ua.edge)
# Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36 Edg/125.0.0.0

Additional usage

Additional features that fake-useragent now offers since v1.2.0.

If you want to specify your own browser list, you can do that via the browsers argument (default is: ["Google", "Chrome", "Firefox", "Edge", "Opera", "Safari", "Android", "Yandex Browser", "Samsung Internet", "Opera Mobile", "Mobile Safari", "Firefox Mobile", "Firefox iOS", "Chrome Mobile", "Chrome Mobile iOS", "Mobile Safari UI/WKWebView", "Edge Mobile", "DuckDuckGo Mobile", "MiuiBrowser", "Whale", "Twitter", "Facebook", "Amazon Silk"]).
This example will only return random user-agents from Edge and Chrome:

from fake_useragent import UserAgent
ua = UserAgent(browsers=['Edge', 'Chrome'])
ua.random

Note: Fakeuser-agent knowns about browsers: Chrome, Edge, Firefox, Safari, Opera, Android, Opera Mobile, Mobile Safari, Firefox Mobile, Firefox iOS, Chrome Mobile, Chrome Mobile iOS and more (see again full list above).
Note #2: Since fakeuser-agent v2.0.0 the browser names are case-sensitive!

If you want to specify your own operating systems, you can do that via the os argument (default is: ["Windows", "Linux", "Ubuntu", "Chrome OS", "Mac OS X", "Android", "iOS"]).
In this example you will only get Linux user-agents back:

from fake_useragent import UserAgent
ua = UserAgent(os='Linux')
ua.random

Note: Since fakeuser-agent v2.0.0 the OS names are case-sensitive!

You can also specify the type of platforms you want to use, you can do that via the platforms argument (default is ["desktop", "mobile", "tablet"]). This example will only return random user-agents from a mobile device:

from fake_useragent import UserAgent
ua = UserAgent(platforms='mobile')
ua.random

And a random user-agent from a desktop device:

from fake_useragent import UserAgent
ua = UserAgent(platforms='desktop')
ua.random

If you want to return more recent user-agent strings, you can play with the min_version argument (default is: 0.0, meaning all user agents will match).
In this example you get only user agents that have a minimum version of 120.0:

from fake_useragent import UserAgent
ua = UserAgent(min_version=120.0)
ua.random

For backwards compatibility, a minimum usage percentage can still be specified with the min_percentage argument. However, the current list of user agents does not contain this statistic. Therefore all of the user-agents will match.

Hint: Of-course you can combine all those arguments to you liking!

User-agent Python Dictionary

Since version 1.3.0 we now also offer you the following "get" properties which return the whole Python dictionary of the UA, instead of only the user-agent string:

Warning Raw JSON objects (in a Python dictionaries) are returned "as is". Meaning, this data structure could change in the future!

Be aware that these "get" properties below might not return the same key/value pairs in the future. Use ua.random or alike as mentioned above, if you want to use a stable interface.

from fake_useragent import UserAgent
ua = UserAgent()

# Random user-agent dictionary (object)
ua.getRandom
# {'percent': 0.8, 'useragent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36 Edg/116.0.1938.76', 'system': 'Edge 116.0 Win10', 'browser': 'edge', 'version': 116.0, 'os': 'win10'}

# More get properties:
ua.getFirefox
# {'percent': 0.3, 'useragent': 'Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/118.0', 'system': 'Firefox 118.0 Win10', 'browser': 'firefox', 'version': 118.0, 'os': 'win10'}
ua.getChrome
ua.getSafari
ua.getEdge

# And a method with an argument.
# This is exactly the same as using: ua.getFirefox
ua.getBrowser('firefox')

Notes

You can override the fallback string using the fallback parameter, in very rare cases something failed:

from fake_useragent import UserAgent

ua = UserAgent(fallback='your favorite Browser')
# in case if something went wrong, one more time it is REALLY!!! rare case
ua.random == 'your favorite Browser'

If you will try to get unknown browser:

from fake_useragent import UserAgent
ua = UserAgent()
print(ua.unknown)
#Error occurred during getting browser: randm, but was suppressed with fallback.
#Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 Edg/122.0.0.0

If you need to safe some attributes from overriding them in UserAgent by __getattr__ method use safe_attrs you can pass there attributes names. At least this will prevent you from raising FakeUserAgentError when attribute not found.

For example, when using fakeuseragent with injections <https://github.com/tailhook/injections> you need to:

from fake_useragent import UserAgent

ua = UserAgent(safe_attrs=('__injections__',))

Please, do not use if you don't understand why you need this. This is magic for rarely extreme case.

Experiencing issues?

Make sure that you using latest version!

pip install --upgrade fake-useragent

Or if that isn't working, try to install the latest package version like this (2.0.3 is an example, check what the latest version is on PyPi):

pip install fake-useragent==2.0.3

Check version via the Python console:

import fake_useragent

print(fake_useragent.__version__)

And you are always welcome to post issues.

Please do not forget to mention the version that you are using.

For Developers

User-agent Data

The user-agent data we retrieve from user-agents.net. Data is stored in JSONlines format. File is located in the: src/fake_useragent/data directory.

The data JSON file is part of the Python package, see pyproject.toml. Read more about Data files support.

Python Virtual Environment

We encourage to use Python virtual environment before installing Pip packages, like so:

python -m virtualenv env
source env/bin/activate

Local Install

pip install -e .

Tests

pip install -r requirements.txt
tox

Linting

To fix imports using ruff:

pip install -r requirements.txt
ruff check --select="I" --fix .

Fix black code formatting errors:

pip install -r requirements.txt
black .

Note: When ruff v1.0 releases, we most likely move fully towards ruff instead of black.

Changelog

2.2.0 April 14, 2025
- Updated user agents file (JSONL)
- Updated dependencies
- Python 3.8 support is officially dropped
- Python 3.11 support is added
- Improved pyproject.toml file
2.1.0 March 12, 2025
- Speed up the UA converter script and add it to workflow via cronjob
- Dump up dependencies versions
- Updated user agents file (JSONB)
- Improved safe attrs checker and added shape as safe attr by default (

fake-useragent

Description

fake-useragent

Features

Installation

Usage

Additional usage

User-agent Python Dictionary

Notes

Experiencing issues?

For Developers

User-agent Data

Python Virtual Environment

Local Install

Tests

Linting

Changelog