Ada URL Parser

1.31.0 verified Sat Apr 25 auth: no python

Ada URL is a fast, standard-compliant Python library for parsing and manipulating URLs, directly based on the high-performance Ada C++ URL parser. It strictly adheres to the WHATWG URL Standard, offering a more predictable and often faster alternative to Python's built-in `urllib.parse`. The library is actively maintained with frequent updates, often aligning with new releases of the underlying C++ project.

pip install ada-url

Common errors

error ModuleNotFoundError: No module named 'ada_url' ↓

cause The 'ada_url' module is not installed in the Python environment.

fix

Install the module using pip: 'pip install ada_url'.

error ImportError: cannot import name 'URL' from 'ada_url' ↓

cause The 'URL' class is not available in the 'ada_url' module, possibly due to an incorrect import statement.

fix

Ensure the correct import statement: 'from ada_url import URL'.

error AttributeError: module 'ada_url' has no attribute 'parse_url' ↓

cause The 'parse_url' function is not defined in the 'ada_url' module, possibly due to a version mismatch or incorrect import.

fix

Verify the module's documentation for the correct usage or update to the latest version.

error ValueError: invalid URL ↓

cause The string provided to the `URL` constructor or other parsing functions does not conform to the WHATWG URL Standard, which the library strictly enforces.

fix

Ensure 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.

error cannot import name 'url' from 'ada_url' (most likely due to a circular import) ↓

cause 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.

fix

Change the import statement to use the correct capitalization for the class: from ada_url import URL.

Warnings

deprecated Python 3.9 support was deprecated in version 1.28.0. Users are encouraged to upgrade to Python 3.10 or newer. ↓

fix Upgrade your Python environment to 3.10 or later.

gotcha The `__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. ↓

fix Access `url_obj.href` for the full URL string if needed, but be mindful of exposing sensitive information.

gotcha While `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. ↓

fix Benchmark `ada-url` against `can_ada` in your specific use case if micro-optimizations for URL parsing speed are critical.

gotcha Ada-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. ↓

fix Thoroughly test URL parsing and serialization logic when migrating from `urllib.parse` or integrating with non-WHATWG-compliant systems to ensure consistent behavior.

breaking The 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. ↓

fix Review 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.

Install compatibility last tested: 2026-04-25

runtime status import time mem disk

3.10-alpine 0.01s 0.7MB 28.5M

3.10-slim 0.01s 0.7MB 27M

3.11-alpine 0.03s 1.1MB 30.6M

3.11-slim 0.02s 1.1MB 29M

3.12-alpine 0.02s 0.8MB 22.4M

3.12-slim 0.02s 0.8MB 21M

3.13-alpine 0.02s 0.9MB 22.1M

3.13-slim 0.02s 0.7MB 20M

3.9-alpine 0.02s 0.5MB 28.4M

3.9-slim 0.01s 0.5MB 27M

Imports

URL
```
from ada_url import URL
```
parse_url
```
from ada_url import parse_url
```
URLSearchParams
```
from ada_url import URLSearchParams
```

Quickstart last tested: 2026-04-25

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']}")