{"id":18947355,"url":"https://github.com/lennolium/simple-useragent","last_synced_at":"2026-03-07T17:03:09.789Z","repository":{"id":220809846,"uuid":"752321800","full_name":"Lennolium/simple-useragent","owner":"Lennolium","description":"Seamlessly fetch authentic and current user agents with ease.","archived":false,"fork":false,"pushed_at":"2025-02-10T15:03:51.000Z","size":525,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T11:44:55.476Z","etag":null,"topics":["browser-header-spoofing","faker","python","python3","scraper","user-agent-spoofer","useragent","web","web-scraping"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/simple-useragent/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Lennolium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":["Lennolium"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://www.paypal.me/smogg","https://buymeacoffee.com/lennolium"]}},"created_at":"2024-02-03T16:18:31.000Z","updated_at":"2025-03-07T11:55:47.000Z","dependencies_parsed_at":"2024-02-17T19:45:38.025Z","dependency_job_id":null,"html_url":"https://github.com/Lennolium/simple-useragent","commit_stats":null,"previous_names":["lennolium/simple-useragent"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lennolium%2Fsimple-useragent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lennolium%2Fsimple-useragent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lennolium%2Fsimple-useragent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lennolium%2Fsimple-useragent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lennolium","download_url":"https://codeload.github.com/Lennolium/simple-useragent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249166154,"owners_count":21223392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser-header-spoofing","faker","python","python3","scraper","user-agent-spoofer","useragent","web","web-scraping"],"created_at":"2024-11-08T13:09:45.621Z","updated_at":"2026-03-07T17:03:09.783Z","avatar_url":"https://github.com/Lennolium.png","language":"HTML","funding_links":["https://github.com/sponsors/Lennolium","https://www.paypal.me/smogg","https://buymeacoffee.com/lennolium"],"categories":[],"sub_categories":[],"readme":"\u003c!--- Logo --\u003e\n\n\u003cdiv align=\"center\"\u003e  \n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/Lennolium/simple-useragent/main/img/banner_dark.png\" width=\"750vw\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/Lennolium/simple-useragent/main/img/banner_light.png\" width=\"750vw\"\u003e\n  \u003cimg alt=\"Application Banner\" src=\"https://raw.githubusercontent.com/Lennolium/simple-useragent/main/img/banner_light.png\" width=\"750vw\"\u003e\n\u003c/picture\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n\u003c!--- Badges --\u003e\n\n\u003cdiv align=\"center\"\u003e \n  \u003ca href=\"https://github.com/Lennolium/simple-useragent/branches\" \u003e \n    \u003cimg src=\"https://img.shields.io/github/last-commit/Lennolium/simple-useragent?label=Last%20Updated\u0026color=orange\" alt=\"last updated\" \u003e\n  \u003ca\u003e\u003c/a\u003e  \n   \u003ca href=\"https://app.codacy.com/gh/Lennolium/simple-useragent/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade\" \u003e \n    \u003cimg src=\"https://app.codacy.com/project/badge/Grade/747e8fea69394b10a1f4627babddcf4f\" alt=\"code quality\" \u003e\n    \u003ca\u003e\u003c/a\u003e\n   \u003ca href=\"https://github.com/Lennolium/simple-useragent/commits/main\" \u003e \n    \u003cimg src=\"https://img.shields.io/github/commit-activity/m/Lennolium/simple-useragent?label=Commit%20Activity\u0026color=yellow\" \nalt=\"commit activity\" \u003e\n     \u003ca\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/Lennolium/simple-useragent/releases\" \u003e \n    \u003cimg src=\"https://img.shields.io/badge/Version-0.1.6-brightgreen\" \nalt=\"stable version\" \u003e\n     \u003cbr\u003e\n  \u003ca href=\"https://github.com/Lennolium/simple-useragent/issues\" \u003e \n    \u003cimg src=\"https://img.shields.io/github/issues-raw/Lennolium/simple-useragent?label=Open%20Issues\u0026color=critical\" alt=\"open issues\" \u003e\n  \u003ca href=\"https://github.com/Lennolium/simple-useragent/issues?q=is%3Aissue+is%3Aclosed\" \u003e \n    \u003cimg src=\"https://img.shields.io/github/issues-closed-raw/Lennolium/simple-useragent?label=Closed%20Issues\u0026color=inactive\" alt=\"closed issues\" \u003e \n     \u003ca href=\"https://pepy.tech/project/simple-useragent\" \u003e \n    \u003cimg src=\"https://static.pepy.tech/badge/simple-useragent\" alt=\"pypi downloads\" \u003e\n  \u003ca href=\"https://github.com/Lennolium/simple-useragent/blob/main/LICENSE\" \u003e \n    \u003cimg src=\"https://img.shields.io/github/license/Lennolium/simple-useragent?label=License\u0026color=blueviolet\" alt=\"License\" \u003e \n  \u003ca\u003e\u003c/a\u003e \u003c/a\u003e \u003c/a\u003e \u003c/a\u003e \u003c/a\u003e \u003c/a\u003e \u003c/a\u003e \u003c/a\u003e \u003c/a\u003e\n\u003c/div\u003e\n\n\u003c!--- Title Line --\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e\u003c/h1\u003e \n\u003c/div\u003e\n\n\u003c!--- Description --\u003e\n\n\u003cdiv align=\"center\"\u003e\nFetches real world, up-to-date user agents for use in web scraping to avoid bot detection.\nNo more fake or outdated user agents, only user agents of real users.\nYou can either get random or usage-weighted user agents. It caches\nthe user agents locally to avoid unnecessary API calls, and refreshes them automatically every 24 hours\nfrom the public API of \u003ca href=\"https://useragents.me/\"\u003euseragents.me\u003c/a\u003e. If you need full-fledge fake browser\nheaders including client hints like sec-ch-ua, sec-fetch-site and more, check out my \n\u003ca href=\"https://github.com/Lennolium/simple-header\"\u003esimple-header\u003c/a\u003e package.\u003cbr\u003e\u003cbr\u003e\n\n[![Donate](https://img.shields.io/badge/Donate-Paypal-blue?style=flat-square\u0026logo=paypal)](https://www.paypal.me/smogg)\n[![BuyMeACoffee](https://img.shields.io/badge/Buy%20me%20a-Coffee-f5d132?style=flat-square\u0026logo=buymeacoffee)](https://buymeacoffee.com/lennolium)\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003e\u003c/h3\u003e  \n    \u003c/div\u003e     \n\u0026nbsp;\n\n\u003c!--- Table of contents --\u003e\n\n## Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Quickstart](#quickstart)\n  - [Advanced Usage](#advanced-usage)\n  - [Settings and Parameters](#settings-and-parameters)\n- [Development](#development)\n- [Contributors](#contributors)\n- [Credits](#credits)\n- [License](#license)\n\n\u0026nbsp;\n\n\u003c!--- Features --\u003e\n\n## Features\n\n- __Up-to-date:__ No fake or outdated user agents. `Only real world data`, refreshed every 24 hours.\n- __Wide Support:__ User Agents for Windows, macOS, Linux, Android and iOS devices: Google Chrome, Firefox, Safari, Edge, Opera, Whale and QQ browsers.\n- __Lightweight:__ Caches user agents locally to consume minimal system resources.\n- __Simple:__ Easy to use and understand with a clean and simple API.\n- __Compatible:__ Supports `Python 3.8 and above`. Runs on Windows, macOS and Linux.\n- __Tested:__ Has 99% test coverage and is continuously tested.\n- __Privacy:__ Protects the user by not collecting or sending any personal data.\n- __Open Source:__ Provides transparency and allows community contributions for continuous development.\n\n\u0026nbsp;\n\n\u003c!--- Installation --\u003e\n\n## Installation\n\nJust install the package from [PyPi](https://pypi.org/project/simple-useragent/) using pip:\n\n```bash\npip install simple-useragent\n```\n\n\u0026nbsp;\n\n\u003c!--- Usage --\u003e\n\n## Usage\n\n#### Quickstart\n\nJust import the package and use the convenience functions. For more advanced usage, you can initialize the class to set custom settings.\n\n```python\nimport simple_useragent as sua\n\nsua.get(num=2, mobile=True)  # List of the 2 most common mobile user agents (attributes explained below).\n# [UserAgent('Mozilla/5.0 (Android ...'), UserAgent('Mozilla/5.0 (iPhone; ...')]\n\nsua.get_list(shuffle=True, force_cached=True)  # Random list of available desktop user agents strings.\n# ['Mozilla/5.0 ...', 'Mozilla/5.0 (iPhone ...', 'Mozilla/5.0 (iPhone ...', ...]\n\nsua.get_dict()  # Dictionary with all desktop and mobile user agents.\n# {'desktop': ['Mozilla/5.0 ...', ...] 'mobile': ['Mozilla/5.0 (iPhone ...', ...]}\n```\n\u0026nbsp;\n\n#### Advanced Usage\n\nImport the package and initialize the UserAgents class to set custom settings (optional, see [Settings and Parameters](#settings-and-parameters) for details).\n```python\nimport simple_useragent as sua\n\nsimple_ua = sua.UserAgents(max_retries=3, timeout=5, cache_duration=86400, cache_location='example/path/to/folder')\n```\n\u0026nbsp;\n\nFetching User Agents.\n```python\n# Fetch a specified number of random mobile user agent instances (with settings from the class above).\nsimple_ua.get(num=2, shuffle=True, mobile=True)\n# [UserAgent('Mozilla/5.0 (iPhone ...'), UserAgent('Mozilla/5.0 (iPhone; ...')]\n```  \n\u0026nbsp;\n\nYou can also use the convenience functions to get user agents without initializing the class.\n```python\nsua.get(num=2, mobile=True)  # List of the 2 most common mobile user agent (attributes explained below).\n# [UserAgent('Mozilla/5.0 (Android ...'), UserAgent('Mozilla/5.0 (iPhone; ...')]\n\nsua.get_list(force_cached=True)  # List of all available desktop user agents as strings.\n# ['Mozilla/5.0 ...', 'Mozilla/5.0 (iPhone ...', 'Mozilla/5.0 (iPhone ...', ...]\n\nsua.get_dict()  # Dictionary with all desktop and mobile user agents.\n# {'desktop': ['Mozilla/5.0 ...', ...] 'mobile': ['Mozilla/5.0 (iPhone ...', ...]}\n```\n\u0026nbsp;\n\nThe instance offers attributes for the user agent properties.\n```python\n# Parse a custom string directly to the UserAgent class and access its attributes.\nobj = sua.parse('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36')\nobj.string  # 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit ...'\nobj.browser  # 'Chrome', 'Firefox', 'Safari', 'Edge', 'IE', 'Opera', 'Whale', 'QQ Browser', 'Samsung Browser', 'Other'\nobj.browser_version  # '110', '109', '537', ...\nobj.browser_version_minor  # '0', '1', '36', ...\n\n# You can also access the attributes with square brackets.\nobj = sua.get(num=1, shuffle=True)[0]\nobj['os']  # 'Windows', 'macOS', 'Linux', 'Android', 'iOS', 'Other'\nobj['os_version']  # '10', '7', '11', '14', ...\nobj['os_version_minor']  # '0', '1', '2', ...\nobj['mobile']  # True / False\n```\n\u0026nbsp;\n\n#### Settings and Parameters\n\nThe functions can take the following parameters:\n\n- __num:__ The number of user agents to fetch (default: _None_ = gets you all user agents available).\n- __mobile:__ Fetch mobile or desktop user agents (default: _False_ = desktop).\n- __shuffle:__ Whether to shuffle/randomize the order of user agents (default: _False_ = ordered by usage).\n- __force_cached:__ Force the use of memory or file cached user agents (default: _None_ = fetches new user agents if cache is outdated, _False_ = always call the API, _True_ = always use the cache).\n\n\u0026nbsp;\n\nYou can set custom preferences when initializing the class with `UserAgents(...)`.\n\n- __max_retries:__ The maximum number of retries to reach the API, before falling back to local cache (default: _3_).\n- __timeout:__ The timeout in seconds for the API request (default: _5_).\n- __cache_duration:__ The duration in seconds for the user agents to be cached (default: _86400_ = 1 day).\n- __cache_location:__ The folder in which the user agents are cached, specific to the OS. You can see the default location with `UserAgents._cache_location`.\n\n\u0026nbsp;\n\n\u003e __Notes:__\n\u003e \n\u003e - The user agents are cached locally to avoid unnecessary API calls, and are refreshed automatically every 24 hours.\n\u003e - During runtime the user agents are stored in memory and written to a cache file for persistence and performance.\n\u003e - Every time you invoke a simple-useragent function, it is automatically checked for outdated user agents.\n\n\u0026nbsp;\n\n\u003c!--- Development --\u003e\n\n## Development\n\nAs an open-source project, I strive for transparency and collaboration in my development process. I greatly \nappreciate any contributions members of our community can provide. Whether you are fixing bugs, proposing features, \nimproving documentation, or spreading awareness - your involvement strengthens the project. Please review the \n[code of conduct](https://github.com/Lennolium/simple-useragent/blob/main/.github/CODE_OF_CONDUCT.md) to understand how we work together \nrespectfully.\n\n- __Bug Report:__ If you are experiencing an issue while using the package, please [create an issue](https://github.com/Lennolium/simple-useragent/issues/new/choose).\n- __Feature Request:__ Make this project better by [submitting a feature request](https://github.com/Lennolium/simple-useragent/discussions/new?category=feature-requests).\n- __Documentation:__ Improve our documentation by [adding a wiki page](https://github.com/Lennolium/simple-useragent/wiki).\n- __Community Support:__ Help others on [GitHub Discussions](https://github.com/Lennolium/simple-useragent/discussions).\n- __Security Report:__ Report critical security issues via our [template](https://github.com/Lennolium/simple-useragent/blob/main/.github/SECURITY.md).\n\n\u0026nbsp;\n\n\u003c!-- Contributors --\u003e\n\n## Contributors\n\nThank you so much for giving feedback, implementing features and improving the code and project!\n\n\u003ca href = \"https://github.com/Lennolium/simple-useragent/graphs/contributors\"\u003e\n  \u003cimg src = \"https://contrib.rocks/image?repo=Lennolium/simple-useragent\" alt=\"Contributors\"/\u003e \n\u003c/a\u003e\n\n\u0026nbsp;\n\n\u003c!--- Credits --\u003e\n\n## Credits\n\nFull credits are in the [ACKNOWLEDGMENTS](https://github.com/Lennolium/simple-useragent/blob/main/ACKNOWLEDGMENTS) file.\n\n\u0026nbsp;\n\n\u003c!--- License --\u003e\n\n## License\n\nProvided under the terms of the [GNU GPL3 License](https://www.gnu.org/licenses/gpl-3.0.en.html) © Lennart Haack 2024.\n\nSee [LICENSE](https://github.com/Lennolium/simple-useragent/blob/main/LICENSE) file for details.\nFor the licenses of used third party libraries and software, please refer to the [ACKNOWLEDGMENTS](https://github.com/Lennolium/simple-useragent/blob/main/ACKNOWLEDGMENTS) file.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flennolium%2Fsimple-useragent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flennolium%2Fsimple-useragent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flennolium%2Fsimple-useragent/lists"}