{"id":1774,"library":"user-agents","title":"User-Agents Library","description":"The `user-agents` library is a simple Python library for identifying devices (phones, tablets, PCs) and their capabilities by parsing browser user agent strings. It wraps the `ua-parser` library and provides a more convenient object-oriented interface. The current version is 2.2.0, and releases are made periodically to incorporate updates from `ua-parser` and add minor features.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/selwin/python-user-agents","tags":["user-agent","parsing","browser","device","mobile","web"],"install":[{"cmd":"pip install user-agents","lang":"bash","label":"Install user-agents"}],"dependencies":[{"reason":"Core dependency for parsing user-agent strings and providing definition files.","package":"ua-parser","optional":false}],"imports":[{"symbol":"parse","correct":"from user_agents import parse"}],"quickstart":{"code":"from user_agents import parse\n\n# Example user agent strings\nuser_agent_string_mobile = 'Mozilla/5.0 (Linux; Android 10; SM-G973F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Mobile Safari/537.36'\nuser_agent_string_desktop = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'\nuser_agent_string_empty = ''\n\n# Parse a mobile user agent\nuser_agent_mobile = parse(user_agent_string_mobile)\nprint(f\"Mobile UA: {user_agent_mobile.is_mobile} (Mobile)\")\nprint(f\"Device: {user_agent_mobile.device.family}, OS: {user_agent_mobile.os.family} {user_agent_mobile.os.version_string}\")\nprint(f\"Browser: {user_agent_mobile.browser.family} {user_agent_mobile.browser.version_string}\\n\")\n\n# Parse a desktop user agent\nuser_agent_desktop = parse(user_agent_string_desktop)\nprint(f\"Desktop UA: {user_agent_desktop.is_pc} (PC)\")\nprint(f\"Device: {user_agent_desktop.device.family}, OS: {user_agent_desktop.os.family} {user_agent_desktop.os.version_string}\")\nprint(f\"Browser: {user_agent_desktop.browser.family} {user_agent_desktop.browser.version_string}\\n\")\n\n# Parse an empty user agent\nuser_agent_empty = parse(user_agent_string_empty)\nprint(f\"Empty UA is_pc: {user_agent_empty.is_pc}\")\nprint(f\"Empty UA device family: {user_agent_empty.device.family}\")","lang":"python","description":"This quickstart demonstrates how to parse different user agent strings using `user_agents.parse` and access various properties like device type, operating system, and browser information. It also shows how the library handles empty strings gracefully, returning an object with 'Other' or empty values."},"warnings":[{"fix":"Ensure your `ua-parser` dependency is updated to at least `0.10.0` or allow pip to upgrade it automatically (`pip install --upgrade user-agents`). Consider using a virtual environment to manage dependencies.","message":"Version 2.2.0 and newer explicitly require `ua-parser >= 0.10.0`. If you have an older version of `ua-parser` pinned in your environment, upgrading `user-agents` might lead to dependency conflicts or installation failures.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Always check the returned `UserAgent` object's properties (e.g., `user_agent.is_unknown` or `user_agent.device.family == 'Other'`) if you need to specifically handle empty or unidentifiable user agents. You may want to implement explicit checks for empty strings before calling `parse()` if an error is preferred.","message":"Parsing an empty or `None` user agent string does not raise an error. Instead, `parse('')` returns a `UserAgent` object where properties like `is_pc`, `is_mobile`, `browser.family`, `os.family`, etc., will default to `False`, `None`, or 'Other'/'Unknown' respectively. This might not be the expected behavior for users anticipating an error or `None`.","severity":"gotcha","affected_versions":"All"},{"fix":"Regularly upgrade the `user-agents` package (`pip install --upgrade user-agents`) to ensure you have the latest `ua-parser` definitions available. The `user-agents` library's `install_requires` ensures a compatible `ua-parser` version is installed.","message":"The underlying user agent definitions are provided by the `ua-parser` library. For the most accurate and up-to-date parsing, it's crucial that `ua-parser` (and thus `user-agents`) is kept up-to-date. Outdated versions may incorrectly identify newer devices or browsers.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}