Install & Compatibility
Where this runs
tested against v1.0.2 · 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
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ from ua_parser import parse
parse_user_agent
✓ from ua_parser import parse_user_agent
parse_os
✓ from ua_parser import parse_os
parse_device
✓ from ua_parser import parse_device
This quickstart demonstrates how to use `ua-parser` to parse common User-Agent strings and extract information about the browser, operating system, and device. The `parse` function returns a Result object containing detailed attributes.
from ua_parser import parse
# Example User-Agent strings
ua_string_desktop = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36'
ua_string_mobile = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Mobile/15E148 Safari/604.1'
# Parse a desktop User-Agent string
parsed_ua_desktop = parse(ua_string_desktop)
print(f"Desktop UA: {ua_string_desktop}")
print(f" Browser: {parsed_ua_desktop.user_agent.family} {parsed_ua_desktop.user_agent.major}.{parsed_ua_desktop.user_agent.minor}")
print(f" OS: {parsed_ua_desktop.os.family} {parsed_ua_desktop.os.major}.{parsed_ua_desktop.os.minor}")
print(f" Device: {parsed_ua_desktop.device.family}\n")
# Parse a mobile User-Agent string
parsed_ua_mobile = parse(ua_string_mobile)
print(f"Mobile UA: {ua_string_mobile}")
print(f" Browser: {parsed_ua_mobile.user_agent.family} {parsed_ua_mobile.user_agent.major}.{parsed_ua_mobile.user_agent.minor}")
print(f" OS: {parsed_ua_mobile.os.family} {parsed_ua_mobile.os.major}.{parsed_ua_mobile.os.minor}")
print(f" Device: {parsed_ua_mobile.device.family}")
Debug
Known issues
gotchaWithout installing optional dependencies like 'regex' or 'google-re2', the library relies on a pure Python resolver which is significantly slower, especially on non-CPython runtimes. This can lead to unexpected performance bottlenecks.fixInstall with recommended optional dependencies: `pip install 'ua-parser[regex]'` for optimal performance.
affects: All versions
breakingGoogle Chrome is progressively 'freezing' User-Agent strings and moving towards User-Agent Client Hints. Libraries relying solely on traditional User-Agent strings (like `ua-parser` by default) may experience declining accuracy for modern Chrome browsers over time as less information is available in the frozen string.fixBe aware of this industry shift. Consider supplementing `ua-parser` with a solution that handles User-Agent Client Hints if high accuracy for Chrome is critical. The `ua-parser` library itself does not inherently parse client hints.
affects: All versions, increasingly impactful over time
gotchaThe accuracy of user agent parsing relies on up-to-date regex definitions. While `ua-parser` is maintained, keeping its internal regexes current with the latest devices and browsers might require manual updates or more frequent dependency updates compared to solutions that offer automatic regex updates.fixRegularly update the `ua-parser` library to benefit from the latest regex definitions. For critical applications, monitor parsing results and consider how the underlying `uap-core` definitions are updated.
affects: All versions
deprecatedIn versions prior to 1.0 (e.g., 0.x), the parser could be re-created on every access if not explicitly handled, negating the benefits of faster regex engines and caching. This was a common performance footgun.fixUpgrade to `ua-parser` version 1.0 or newer. If staying on 0.x, ensure the global parser is explicitly set or cached to avoid re-creation overhead.
affects: <1.0
gotchaInstalling the `google-re2` optional dependency (part of `ua-parser[re2]`) requires a C++ compiler (like `g++`) and related development headers to be present in the build environment. Minimal Python images (e.g., `python:*-slim`) often lack these, leading to build failures for `google-re2`.fixTo use the `re2` engine, ensure your environment has a C++ compiler (e.g., install `build-essential` or `g++` package) and Python development headers before attempting to install `ua-parser[re2]`. Alternatively, consider using `ua-parser[regex]` which relies on `ua-parser-rs` and may have fewer system-level build dependencies.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ua_parser'
The 'ua-parser' library is not installed in the current Python environment.
AttributeError: module 'ua_parser' has no attribute 'Parse'
The 'Parse' function is located within the 'user_agent_parser' submodule, not directly under the top-level 'ua_parser' module, when 'import ua_parser' is used.
fixfrom ua_parser import user_agent_parser
parsed_ua = user_agent_parser.Parse(ua_string)
ImportError: cannot import name 'Parse' from 'ua_parser'
The 'Parse' function is not directly exposed by the top-level 'ua_parser' package; it must be imported from its submodule.
fixfrom ua_parser import user_agent_parser
parsed_ua = user_agent_parser.Parse(ua_string)
Upgrade
Version history
1.0.2latest on PyPI · released Apr 5, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
regexoptionalSignificantly faster parsing, strongly recommended. `ua-parser` will auto-detect and use it if installed.
google-re2optionalAlternative faster regex engine, slightly slower than `regex` but still much faster than pure Python.
PyYAMLoptionalEnables loading rulesets from YAML files.