Install & Compatibility
Where this runs
tested against v4.0.0 · 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.018s · 28.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.016s · 26MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
URL
✓ from ada_url import URL
parse_url
✓ from ada_url import parse_url
URLSearchParams
✓ from ada_url import URLSearchParams
This quickstart demonstrates parsing a URL into an `URL` object to access its components, modifying a component, and using the `parse_url` function to get a dictionary representation.
import ada_url
# Parse a URL using the URL class
url_obj = ada_url.URL('https://user:pass@example.org:8080/path/to/resource?query=value#fragment')
print(f"Original URL: {url_obj.href}")
print(f"Protocol: {url_obj.protocol}")
print(f"Hostname: {url_obj.hostname}")
print(f"Port: {url_obj.port}")
print(f"Pathname: {url_obj.pathname}")
print(f"Search: {url_obj.search}")
print(f"Hash: {url_obj.hash}")
# Modify a URL component
url_obj.port = '443'
url_obj.protocol = 'https:'
print(f"Modified URL: {url_obj.href}")
# Use high-level parse_url function (returns a dictionary)
parsed_dict = ada_url.parse_url('https://example.com/api?id=123&name=test')
print(f"Parsed dictionary: {parsed_dict['search']}")
Debug
Known issues
deprecatedPython 3.9 support was deprecated in version 1.28.0. Users are encouraged to upgrade to Python 3.10 or newer.fixUpgrade your Python environment to 3.10 or later.
affects: >=1.28.0
gotchaThe `__repr__` of `URL` objects now redacts passwords for security reasons. If you relied on the full URL string (including sensitive credentials) in `__repr__` output for debugging or logging, this behavior has changed.fixAccess `url_obj.href` for the full URL string if needed, but be mindful of exposing sensitive information.
affects: >=1.31.0
gotchaWhile `ada-url` is significantly faster than Python's `urllib.parse`, it uses CFFI for its bindings. For scenarios requiring absolute maximum performance with minimal Python-C overhead, alternative bindings like `can_ada` (which uses `pybind11`) might offer further speed improvements.fixBenchmark `ada-url` against `can_ada` in your specific use case if micro-optimizations for URL parsing speed are critical.
affects: All versions
gotchaAda-url strictly follows the WHATWG URL Standard. This can lead to different parsing behaviors compared to Python's `urllib.parse`, which does not strictly adhere to any single standard (neither WHATWG nor older RFCs). Be aware of potential differences when migrating or when interacting with systems that follow older RFCs.fixThoroughly test URL parsing and serialization logic when migrating from `urllib.parse` or integrating with non-WHATWG-compliant systems to ensure consistent behavior.
affects: All versions
breakingThe underlying Ada C++ library (which `ada-url` binds to) has its own breaking changes between major versions (e.g., Ada v3.0 introduced C++20 requirements and changed error types). While the Python bindings aim for stability, users building from source or relying on very specific low-level behaviors might indirectly encounter these breaking changes or require updated C++ toolchains.fixReview the changelogs of the `ada-python` library and the upstream `ada` C++ library when upgrading. Ensure your build environment meets the latest C++ compiler requirements if building from source.
affects: Potentially when underlying Ada C++ library updates (e.g., Ada v3.0, corresponding to `ada-url` v1.23.0 and later).
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ada_url'
The 'ada_url' module is not installed in the Python environment.
fixInstall the module using pip: 'pip install ada_url'.
ImportError: cannot import name 'URL' from 'ada_url'
The 'URL' class is not available in the 'ada_url' module, possibly due to an incorrect import statement.
fixEnsure the correct import statement: 'from ada_url import URL'.
AttributeError: module 'ada_url' has no attribute 'parse_url'
The 'parse_url' function is not defined in the 'ada_url' module, possibly due to a version mismatch or incorrect import.
fixVerify the module's documentation for the correct usage or update to the latest version.
ValueError: invalid URL
The string provided to the `URL` constructor or other parsing functions does not conform to the WHATWG URL Standard, which the library strictly enforces.
fixEnsure the input URL string is well-formed and standard-compliant. You can use `URL.can_parse(url_string)` to check validity before attempting to parse, or wrap parsing in a `try-except ValueError` block.
cannot import name 'url' from 'ada_url' (most likely due to a circular import)
The `URL` class is imported with incorrect capitalization (e.g., 'url' instead of 'URL'). Python is case-sensitive, and the main URL class in `ada-url` is capitalized.
fixChange the import statement to use the correct capitalization for the class: `from ada_url import URL`.
Upgrade
Version history
4.0.0latest on PyPI · released Jul 28, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
cffirequiredUsed for Python-C foreign function interface to the underlying Ada C++ library.