fake-useragent

library2.2.0pypypi✓ verified 30d ago

fake-useragent is a Python library that generates up-to-date and realistic browser user-agent strings for web scraping and testing purposes. It dynamically fetches a database of real-world user agents to provide diverse and current options. The current version is 2.2.0, with minor releases occurring every few months to update the user-agent database or fix small issues.

testing http-networking

pip install fake-useragent

github ↗package ↗

INSTALL

IMPORT

SIG · FAKE-USERAGENT

fake-useragent

testingpythonv2.2.0

Install

1.6s avg

Import

135ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.2.0 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.148s · 20.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.122s · 21MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UserAgent

✓ from fake_useragent import UserAgent

FakeUserAgentError

✓ from fake_useragent import FakeUserAgentError

Exception for handling errors like network issues during data fetching.

This quickstart demonstrates how to initialize `UserAgent` and retrieve various types of user-agent strings. It includes basic error handling for potential network issues during the initial data download or cache refresh.

from fake_useragent import UserAgent, FakeUserAgentError try: ua = UserAgent() print(f"Random User-Agent: {ua.random}") print(f"Chrome User-Agent: {ua.chrome}") print(f"Firefox User-Agent: {ua.firefox}") print(f"User-Agent for macOS: {ua.get_ua('chrome', os='macos')}") print(f"User-Agent for desktop: {ua.get_ua(platform='desktop')}") except FakeUserAgentError as e: print(f"Error fetching user agents: {e}") print("This might be due to network issues or the first-time data download failing.")

Debug

Known issues

breakingSince version 2.0.0, OS and browser options are case-sensitive. Previously, they might have been implicitly converted or handled with more flexibility.

fix

Ensure all OS and browser option parameters (e.g., in `ua.get_ua(browser='Chrome', os='Windows')`) are passed with the correct casing as specified in the documentation (e.g., 'chrome', 'firefox', 'windows', 'macos').

affects: 2.0.0+

breakingIn version 2.0.0, the `platform` type value 'pc' was changed to 'desktop'. If you were specifically requesting desktop user agents using `platform='pc'`, your code will no longer work as expected.

fix

Replace `platform='pc'` with `platform='desktop'` when calling methods like `ua.get_ua()` to specify desktop user agents.

affects: 2.0.0+

gotchaSince version 1.5.0, the `min_percentage` parameter for filtering user agents is effectively useless. The new data sources introduced in this version and later do not provide usage statistics, so this filter is ignored.

fix

Remove `min_percentage` from your calls, as it will not filter user agents based on usage. Rely on other parameters for selection.

affects: 1.5.0+

gotchafake-useragent requires Python 3.9 or newer since version 2.0.1. Attempting to use it with older Python versions will result in compatibility errors.

fix

Upgrade your Python environment to version 3.9 or newer if you are using fake-useragent 2.0.1 or later.

affects: 2.0.1+

gotchaOn its first run (or when the cache expires), `fake-useragent` attempts to download a JSON file (~500KB) from an external source (currently intoli.com). This can introduce network delays, fail due to connectivity issues, or be blocked by firewalls/proxies.

fix

Ensure reliable network access for initialization. Handle `FakeUserAgentError` for network-related failures. For restricted environments, consider pre-caching the data or using options like `cache=False` (though this fetches data on every call) or `use_cache_server=False`.

affects: All versions

breakingThe `get_ua()` method was removed. Attempting to call `ua.get_ua()` will result in a `TypeError: 'str' object is not callable` as it is no longer a callable method.

fix

Replace calls to `ua.get_ua()` with direct attribute access like `ua.random`, `ua.chrome`, `ua.firefox`, or use `ua.get('browser_name')` for dynamic selection.

affects: 2.0.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'fake_useragent'

The 'fake-useragent' library is not installed in the Python environment, or the Python interpreter being used cannot find it.

fix

pip install fake-useragent

fake_useragent.errors.FakeUserAgentError: Maximum amount of retries reached

The library failed to download user-agent data from its remote sources after several attempts, typically due to network issues, temporary downtime of the data source, or being blocked.

fix

Initialize the UserAgent with a fallback string: `from fake_useragent import UserAgent; ua = UserAgent(fallback='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3')`

IndexError: list index out of range

This error often occurs when the HTML structure of the external data source from which fake-useragent scrapes its data has changed, causing the library's parsing logic to fail.

fix

Update the fake-useragent library to the latest version (`pip install --upgrade fake-useragent`), which often includes fixes for changes in data sources. Alternatively, use a `fallback` user agent if updates do not resolve the issue.

ModuleNotFoundError: No module named 'fake_useragent.data'

When packaging a Python application with PyInstaller, the internal data files (e.g., 'browsers.json') required by fake-useragent might not be correctly bundled.

fix

Explicitly include the fake-useragent data files when building with PyInstaller: `pyinstaller --onefile --collect-datas=fake_useragent your_script.py`

Upgrade

Version history

2.2.0latest on PyPI · released Apr 14, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

35 hits · last 30 days

node

Resources

githubhttps://github.com/fake-useragent/fake-useragent ↗

packagehttps://pypi.org/project/fake-useragent/ ↗