{"id":716,"library":"tldextract","title":"tldextract","description":"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.","status":"active","version":"5.3.1","language":"python","source_language":"en","source_url":"https://github.com/john-kurkowski/tldextract","tags":["url parsing","domain extraction","public suffix list","tld"],"install":[{"cmd":"pip install tldextract","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"symbol":"tldextract","correct":"import tldextract"},{"note":"As of v5.2.0, ExtractResult was explicitly added to the public interface for easier import.","wrong":"from tldextract.tldextract import ExtractResult","symbol":"ExtractResult","correct":"from tldextract import ExtractResult"},{"note":"As of v5.2.0, 'update' function was explicitly added to the public interface.","symbol":"update","correct":"from tldextract import update"}],"quickstart":{"code":"import tldextract\n\n# Basic extraction\nextract_result = tldextract.extract('http://forums.news.cnn.com/')\nprint(f\"Subdomain: {extract_result.subdomain}\")\nprint(f\"Domain: {extract_result.domain}\")\nprint(f\"Suffix: {extract_result.suffix}\")\nprint(f\"Full host: {extract_result.fqdn}\")\n\n# Example with private suffix\nprivate_extract = tldextract.extract('waiterrant.blogspot.com')\nprint(f\"\\nPrivate domain example: {private_extract.subdomain}.{private_extract.domain}.{private_extract.suffix}\")","lang":"python","description":"Demonstrates basic URL component extraction using `tldextract.extract()` and accessing the results as attributes of the `ExtractResult` object."},"warnings":[{"fix":"Access fields by attribute name (e.g., `result.subdomain`, `result.domain`, `result.suffix`) instead of indexing or unpacking.","message":"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`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"If unpacking, adjust to expect four fields, or preferably, access fields by attribute name to avoid issues with future field additions.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use the `top_domain_under_public_suffix` property instead, which has the same behavior but a more accurate name.","message":"The `registered_domain` property on `ExtractResult` was deprecated in v5.3.0. It will be removed in a future major version.","severity":"deprecated","affected_versions":">=5.3.0"},{"fix":"Upgrade your Python environment to 3.10 or later to continue using the latest `tldextract` versions.","message":"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.","severity":"breaking","affected_versions":">=5.1.3 (for 3.8), >=5.3.1 (for 3.9)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T18:14:38.667Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install tldextract","cause":"The 'tldextract' package is not installed in the current Python environment where you are trying to use it.","error":"ModuleNotFoundError: No module named 'tldextract'"},{"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})`).","cause":"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.","error":"ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed"},{"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.","cause":"The user running the Python process lacks write permissions to the default directory where tldextract attempts to cache the Public Suffix List data.","error":"OSError: [Errno 13] Permission denied"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"5.3.1","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.68,"mem_mb":12.3,"disk_size":"22.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.68,"mem_mb":11.9,"disk_size":"21.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":0.51,"mem_mb":12.3,"disk_size":"22M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.48,"mem_mb":11.9,"disk_size":"22M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.94,"mem_mb":14,"disk_size":"24.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.92,"mem_mb":13.6,"disk_size":"24.0M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.5,"import_time_s":0.77,"mem_mb":14,"disk_size":"25M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":13.6,"disk_size":"24M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.03,"mem_mb":16.4,"disk_size":"15.9M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.03,"mem_mb":16.4,"disk_size":"15.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.1,"import_time_s":0.97,"mem_mb":16.4,"disk_size":"16M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.99,"mem_mb":16.4,"disk_size":"16M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.08,"mem_mb":16.9,"disk_size":"15.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.02,"mem_mb":16.8,"disk_size":"15.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.1,"import_time_s":0.97,"mem_mb":16.9,"disk_size":"16M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.01,"mem_mb":16.8,"disk_size":"16M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":11.5,"disk_size":"21.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.04,"mem_mb":11.6,"disk_size":"21.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.6,"import_time_s":0.53,"mem_mb":11.5,"disk_size":"22M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.51,"mem_mb":11.6,"disk_size":"22M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}