tldextract

5.3.1 · active · verified Sat Mar 28

tldextract accurately separates a URL's subdomain, domain, and public suffix, using the Public Suffix List (PSL). It handles edge cases often missed by naive parsing methods. By default, it supports public ICANN TLDs and their exceptions, with optional support for private domains. The current version is 5.3.1, and the library maintains an active development and release cadence.

Warnings

breaking The `ExtractResult` object changed from a `namedtuple` to a `dataclass` in v5.0.0. This means direct indexing, slicing, or unpacking the result object will raise a `TypeError`.
Fix: Access fields by attribute name (e.g., `result.subdomain`, `result.domain`, `result.suffix`) instead of indexing or unpacking.
breaking The `ExtractResult` object gained a fourth field, `is_private: bool`, in v4.0.0. Code that unpacks the result expecting only 3 fields will break.
Fix: If unpacking, adjust to expect four fields, or preferably, access fields by attribute name to avoid issues with future field additions.
deprecated The `registered_domain` property on `ExtractResult` was deprecated in v5.3.0. It will be removed in a future major version.
Fix: Use the `top_domain_under_public_suffix` property instead, which has the same behavior but a more accurate name.
breaking Support for Python 3.9 was dropped in v5.3.1, and Python 3.8 was dropped in v5.1.3. The library now requires Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or later to continue using the latest `tldextract` versions.
gotcha On its first run, `tldextract` fetches the latest Public Suffix List via an HTTP request and caches it indefinitely in `$HOME/.cache/python-tldextract`. This can cause initial delays or network dependencies in environments where this behavior is not expected.
Fix: To control caching, specify `cache_dir` when initializing `tldextract.TLDExtract()` or manage the `TLDEXTRACT_CACHE` environment variable. You can also explicitly trigger an update via `tldextract --update` CLI command.
gotcha `tldextract` is lenient and performs minimal URL validation. It will attempt to extract components from any string, including partial or malformed URLs, prioritizing ease of use over strict validation.
Fix: If strict URL validation is required, pre-process the input string with a dedicated URL validation library (e.g., `urllib.parse.urlsplit`) before passing it to `tldextract`.

Install

pip install tldextract Install stable version

Imports

tldextract
```
import tldextract
```
ExtractResult
```
from tldextract import ExtractResult
```
As of v5.2.0, ExtractResult was explicitly added to the public interface for easier import.
update
```
from tldextract import update
```
As of v5.2.0, 'update' function was explicitly added to the public interface.

Quickstart

Demonstrates basic URL component extraction using `tldextract.extract()` and accessing the results as attributes of the `ExtractResult` object.

import tldextract

# Basic extraction
extract_result = tldextract.extract('http://forums.news.cnn.com/')
print(f"Subdomain: {extract_result.subdomain}")
print(f"Domain: {extract_result.domain}")
print(f"Suffix: {extract_result.suffix}")
print(f"Full host: {extract_result.fqdn}")

# Example with private suffix
private_extract = tldextract.extract('waiterrant.blogspot.com')
print(f"\nPrivate domain example: {private_extract.subdomain}.{private_extract.domain}.{private_extract.suffix}")

view raw JSON →