Install & Compatibility
Where this runs
tested against v1.24.5 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.054s · 20MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.054s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
URL
✓ from yarl import URL
✗ import yarl; yarl.URL(...)
Always import URL directly from yarl; the top-level module is rarely used on its own.
cache_configure
✓ from yarl import cache_configure
cache_configure(encode_host_size=256)
✗ cache_configure(ip_address_size=256, host_validate_size=256)
ip_address_size and host_validate_size are deprecated since ~1.17 in favour of encode_host_size and will be removed in a future release.
Parse, inspect, and mutate URLs; build from parts; path-join with /; apply query with %.
from yarl import URL
# Parse an existing URL
url = URL('https://user:pw@api.example.com:8080/v1/items?page=1&q=foo#section')
print(url.scheme) # 'https'
print(url.host) # 'api.example.com' (decoded)
print(url.raw_host) # IDNA-encoded form
print(url.port) # 8080 (explicit); None falls back to scheme default
print(url.path) # '/v1/items' (percent-decoded)
print(url.raw_path) # '/v1/items' (percent-encoded, wire form)
print(url.query) # MultiDictProxy with parsed key/value pairs
print(url.query_string) # 'page=1&q=foo'
print(url.fragment) # 'section'
# Build from components — port must be int, not str
base = URL.build(scheme='https', host='api.example.com', port=8080, path='/v1')
print(base) # https://api.example.com:8080/v1
# Path-join (like pathlib)
endpoint = base / 'items' / '42'
print(endpoint) # https://api.example.com:8080/v1/items/42
# Apply a query string with %
with_query = endpoint % {'expand': 'true', 'format': 'json'}
print(with_query)
# Mutation methods return new URL objects (immutable)
updated = endpoint.with_query({'page': '2'}).with_fragment('results')
print(str(updated)) # wire-safe string for HTTP clients
print(updated.human_repr()) # human-readable (non-ASCII decoded)
# Non-ASCII is encoded automatically
unicode_url = URL('https://example.com/пошук?q=кіт')
print(str(unicode_url)) # percent-encoded
print(unicode_url.human_repr()) # readable
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'yarl'
The yarl library is not installed in the current Python environment.
ModuleNotFoundError: No module named 'yarl.url'
The URL class is exposed directly from the top-level yarl package, not from a nested yarl.url submodule.
AttributeError: 'URL' object has no attribute 'add_query_param'
yarl.URL objects are immutable. To modify query parameters, use methods like with_query() or update_query(), which return a new URL object.
fixnew_url = url.with_query(param1='value1', param2='value2')
TypeError: argument should be str or URL, got <class 'int'>
Methods like joinpath() or the / operator for URL objects expect string or other URL objects as arguments for path segments, not other types like integers.
fixEnsure the argument passed is a string representing a path segment or another yarl.URL object. Example: url.joinpath(str(segment_id)) or url / 'segment_name'
Upgrade
Version history
1.24.5latest on PyPI · released Jul 20, 2026
Audit
Dependencies
multidictrequiredRequired — URL.query returns a MultiDictProxy; installed automatically by pip
propcacherequiredRequired — fast property caching layer extracted from yarl ~1.17; installed automatically