tldextract

library5.3.2pypypi✓ verified 29d ago

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.

http-networking data

pip install tldextract

github ↗package ↗

INSTALL

IMPORT

SIG · TLDEXTRACT

tldextract

http-networkingpythonv5.3.2

Install

2.3s avg

Import

618ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.3.2 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.656s · 22.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.3s · import 0.580s · 23MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tldextract

✓ import tldextract

ExtractResult

✓ from tldextract import ExtractResult

✗ from tldextract.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.

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

tldextract --version

Debug

Known issues

breakingThe `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.

affects: >=5.0.0

breakingThe `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.

affects: >=4.0.0

deprecatedThe `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.

affects: >=5.3.0

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

affects: >=5.1.3 (for 3.8), >=5.3.1 (for 3.9)

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tldextract'

The 'tldextract' package is not installed in the current Python environment where you are trying to use it.

fix

pip install tldextract

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

Your system cannot verify the SSL certificate when tldextract attempts to download the Public Suffix List, often due to corporate proxies, firewall rules, or outdated/missing CA certificates.

fix

Ensure your system's CA certificates are up-to-date, configure the REQUESTS_CA_BUNDLE environment variable, or for development purposes, disable SSL verification for PSL updates (e.g., `tldextract.update_public_suffix_list(requests_session=requests.Session(), extra_kwargs={'verify': False})`).

OSError: [Errno 13] Permission denied

The user running the Python process lacks write permissions to the default directory where tldextract attempts to cache the Public Suffix List data.

fix

Set a custom writable cache directory using `tldextract.set_cache_dir('/path/to/a/writable/directory')` before calling `tldextract.extract()`, or adjust the permissions for the default cache location.

Upgrade

Version history

5.3.2latest on PyPI · released Aug 8, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

Agent activity

28 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/john-kurkowski/tldextract ↗

packagehttps://pypi.org/project/tldextract/ ↗