ua-parser-builtins
ua-parser-builtins is the monthly, precompiled user-agent ruleset consumed by the Python ua-parser library. It is data and generated matcher objects, not a parser you call directly. Installing ua-parser brings it in as a required dependency, then ua-parser uses these rules to identify browser, operating-system, and device families without compiling the upstream YAML rules at application startup. The calendar-style version identifies the rules snapshot, so updates can recognize newer browsers, bots, and devices without a ua-parser code release.
Useful and actively refreshed infrastructure for ua-parser, but not something application code should install or import on its own. Depend on ua-parser, pin the resolved monthly snapshot, and treat every classification as a hint rather than identity proof.
Use it if
- You use the current ua-parser package and want its default precompiled uap-core rules rather than loading regexes.yaml yourself
- Cold-start time matters and precompiled matcher objects are preferable to parsing and compiling the upstream YAML rules on every process start
- You want a separately pinnable monthly rules snapshot so recognition data can move independently from parser code
- You need the same generated rules on CPython, PyPy, or GraalPy without maintaining a custom rules build
- You are looking for a callable user-agent API: the package metadata explicitly says this distribution does nothing on its own and has no actual API; install ua-parser instead
- You need rules tailored to your own API clients or traffic: the ua-parser guide recommends a custom ruleset for trimming irrelevant patterns or adding private ones
- Python 3.9 or older is still in production: the current wheel declares Python 3.10 or newer
- You treat user-agent parsing as reliable device detection or authorization: ua-parser returns None for data it cannot match, and client-supplied user-agent strings are trivial to spoof
- Memory is tight: the ua-parser resolver guide reports roughly 40 MB for the basic resolver, around 55 MB for re2, and around 85 MB for the recommended Rust regex resolver on its real-world dataset
Setup reality
Do not add ua-parser-builtins as though it were the application library. The normal installation is `pip install 'ua-parser[regex]'`; ua-parser declares ua-parser-builtins as a dependency and the recommended regex extra adds the fast Rust-backed resolver. The base install falls back to a pure-Python resolver which the ua-parser README calls significantly slower, especially outside CPython, and the resolver guide says it needs caching to be workable. Current releases require Python 3.10 or newer. The builtins version is a calendar snapshot such as 202606, released from whatever is on uap-core's default branch that month, and the exact upstream commit is stored in the wheel's top-level REVISION file. That makes a lockfile important: an unconstrained refresh can change classifications even when your parser code does not change. Unknown or incomplete user agents legitimately produce None fields, so downstream analytics must keep an unknown bucket. If you replace the global parser or load a custom ruleset, that mutation affects every caller in the process. Never use a parsed family, device, or bot label as a security boundary because the input is controlled by the requester.
Patterns
Install ua-parser with the fast resolverinstall-recommended-resolver
python -m pip install 'ua-parser[regex]'This installs ua-parser-builtins transitively. The ua-parser README strongly recommends the regex extra because the pure-Python resolver is significantly slower.
Pin parser code and monthly rulespin-rules-snapshot
# requirements.txt
ua-parser[regex]==1.0.2
ua-parser-builtins==202606The rules package can change classifications independently of parser code, so pin both when reproducible analytics matter.
Parse browser, OS, and device dataparse-complete-user-agent
from ua_parser import parse
result = parse(request.headers.get('User-Agent', ''))
print(result.user_agent)
print(result.os)
print(result.device)This is ua-parser's public API using the bundled rules. Any unmatched component can be None, including all three for an empty string.
Resolve only the browser familyparse-browser-only
from ua_parser import parse_user_agent
browser = parse_user_agent(user_agent_string)
family = browser.family if browser else 'Unknown'Use the domain-specific function when OS and device data are unnecessary; a failed match returns None rather than an object full of empty strings.
Resolve operating-system fieldsparse-operating-system
from ua_parser import parse_os
os = parse_os(user_agent_string)
if os is not None:
version = '.'.join(x for x in (os.major, os.minor, os.patch) if x)
print(os.family, version)Version pieces are optional. Do not join them without filtering None values.
Resolve device family, brand, and modelparse-device
from ua_parser import parse_device
device = parse_device(user_agent_string)
if device is None:
label = 'Unknown'
else:
label = ' '.join(x for x in (device.brand, device.model) if x) or device.familyDesktop user agents often have sparse device data, and every value comes from a spoofable request header.
Create a parser from eager builtinsbuild-parser-from-builtins
from ua_parser import Parser, load_builtins
parser = Parser.from_matchers(load_builtins())
result = parser.parse(user_agent_string)Use the loader exported by ua-parser instead of importing generated MATCHERS from ua_parser_builtins directly.
Build on lazy matcher objectsload-lazy-builtins
from ua_parser import Parser, load_lazy_builtins
parser = Parser.from_matchers(load_lazy_builtins())
print(parser.parse_user_agent(user_agent_string))Lazy matchers defer regex compilation. Resolver selection and caching still determine the real time and memory tradeoff.
Record the active rules snapshotrecord-rules-version
from importlib.metadata import version
rules_version = version('ua-parser-builtins')
print({'ua_rules': rules_version})Log the calendar version with analytics jobs so a sudden classification shift can be tied back to a rules update.
Keep unknown traffic explicithandle-unknown-results
from ua_parser import parse
r = parse(user_agent_string or '')
row = {
'browser': r.user_agent.family if r.user_agent else 'Unknown',
'os': r.os.family if r.os else 'Unknown',
'device': r.device.family if r.device else 'Unknown',
}Do not discard unknowns or guess from substring checks after parsing; that hides rules coverage changes and biases reports.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| ua-parser | PyPI | The package most applications should install; it supplies the public parser API and depends on this ruleset |
| user-agents | PyPI | You prefer convenience properties such as is_mobile and are comfortable with another wrapper around ua-parser data |
| httpagentparser | PyPI | You want a smaller standalone parser with a simple dictionary result and can accept a different rules database |