Random User Agent

Random User Agent is a lightweight Python library that returns realistic user-agent strings drawn from a bundled dataset of more than 326,000 real-world signatures. Instead of hardcoding a handful of user agents or scraping them at runtime, it ships the dataset directly in the package and lets you filter by operating system, hardware type, software name, software engine, software type, and popularity to get agents that match your target audience.

It’s built for scraping and crawling workloads where rotating a believable, filtered set of user-agent headers is the difference between passing as a normal browser and getting blocked — the project’s own GitHub topics list crawler and scrapy alongside user-agent, reflecting that primary use case.

What You Get

• A bundled dataset of 326,000+ real user-agent strings shipped inside the package (no network calls needed)
• Six independent filter dimensions — operating system, hardware type, software name, software engine, software type, and popularity
• Enum-based filter constants (SoftwareName, OperatingSystem, HardwareType, etc.) instead of hand-typed strings
• Both get_user_agents() for a full filtered list and get_random_user_agent() for a single rotate-per-request string

Common Use Cases

• Rotating user-agent headers across scraping/crawling requests to avoid basic bot detection
• Generating realistic user-agent fixtures for load testing or QA automation
• Simulating traffic from specific device/OS/browser combinations (e.g. mobile Android Chrome) in analytics or A/B testing
• Populating default headers for HTTP clients (requests, Scrapy) that would otherwise send an obvious library-default user agent

Under The Hood

Architecture The library is intentionally flat: a single UserAgent class in user_agent.py loads a bundled dataset (data/user_agents.zip, containing a JSON-lines file) and applies up to six independent equality filters — hardware type, software type, software name, software engine, operating system, and popularity — during initialization, with an optional limit to stop early once enough matches are collected. There is no runtime fetching, caching layer, or plugin system; params.py defines large Enum classes that serve purely as string constants passed into the filter arguments, so filtering is done by raw lowercase string comparison rather than typed joins, meaning any change to the underlying dataset’s schema would require updating every enum value in tandem.

Tech Stack Pure Python with no listed runtime dependencies in setup.py — only the standard library (json, os, random, zipfile) is used. The project is packaged with classic setuptools.setup(), bundling the compressed dataset via package_data, targets Python 3 with no version floor pinned, and ships no build tooling, Dockerfile, or CI workflow. Its only external integration is being imported by scraping and crawling stacks (per the GitHub topics crawler, scrapy, user-agent) to populate request headers.

Code Quality No test files exist anywhere in the repository — there is no tests/ directory, no test_* modules, and no CI configuration — so there is no automated verification of the filtering logic. The single source module has no type hints and minimal docstrings, relying on truthy/falsy checks and .lower() normalization rather than validated enum membership; an invalid or misspelled filter value fails silently by matching nothing rather than raising an error.

API Design The public surface is small and easy to pick up — instantiate UserAgent(software_names=[...], operating_systems=[...], limit=100) and call .get_user_agents() or .get_random_user_agent() to get working, realistic user-agent strings with almost no boilerplate. Enum-based filter constants (e.g. SoftwareName.CHROME.value) reduce typos versus hand-typed strings, though the very large flat enums (270+ software names) make discovery via autocomplete somewhat unwieldy.