fake-useragent

library2.2.0pypypi✓ verified 35d 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

github ↗package ↗

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.930 runs

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

glibc

py 3.10–3.930 runs

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

18MB installed

● package 18MB

Code

Verified usage

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

from fake_useragent import UserAgent

Exception for handling errors like network issues during data fetching.

from fake_useragent import FakeUserAgentError

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 footguns

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

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.

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.

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.

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.

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.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

28 hits · last 30 days

bytedance

gptbot

ahrefsbot

sogoubot

claudebot

Resources

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

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