Public Suffix List

1.0.2.20260411 · active · verified Sat Apr 11

Publicsuffixlist is a Python library that implements a parser for the Public Suffix List (PSL). It allows users to extract the public suffix and registrable domain from a given hostname, supporting IDN (unicode and punycoded) and compliant with PSL test data. The library is pure Python, has no external dependencies, and ships with a bundled, frequently updated copy of the PSL. Its current version is 1.0.2.20260411, with new releases often tied to updates of the Public Suffix List itself.

Warnings

gotcha The library does NOT perform domain name validation. It assumes input strings are valid domain names or parts thereof. Invalid inputs (e.g., containing IP addresses, special characters not allowed in DNS, port numbers) should be filtered by the caller.
Fix: Validate domain names using a dedicated domain validation library or custom logic before passing them to `publicsuffixlist` methods.
gotcha When dealing with IDNA-encoded domains, especially those with mixed Unicode characters, ensure correct encoding handling. While the module converts the PSL to process IDNA by default, for specific UTF-8 domain use cases (e.g., '食狮.com.cn'), you might need to set the `IDNA-encoding` flag to `False` on instantiation. Failure to do so can lead to incorrect results.
Fix: For UTF-8 domains, consider `psl = PublicSuffixList(idna_encoding=False)` if default behavior yields incorrect results. For ambiguous Punycode, explicitly `domain.encode("idna").decode("ascii")` before passing.
gotcha The Public Suffix List (PSL) is regularly updated. Using an outdated list, even one bundled with an older version of the library, can lead to incorrect classification of domains, potentially impacting security features like cookie handling or domain highlighting.
Fix: Keep the `publicsuffixlist` library updated to get the latest bundled PSL. For critical applications, consider using the provided updater script (`python -m publicsuffixlist.update`) or fetching the latest list dynamically, though this library often updates its bundled list with releases.
deprecated This library is a fork and continuation of the `publicsuffix` package. The original `publicsuffix` library is deprecated and no longer maintained. Using `publicsuffixlist` (or `publicsuffix2`) is recommended.
Fix: Replace `publicsuffix` imports and usage with `publicsuffixlist`. Be aware of minor API differences if directly porting, though `publicsuffixlist` aims for similar functionality.

Install

pip install publicsuffixlist Install stable version

Imports

PublicSuffixList
```
from publicsuffixlist import PublicSuffixList
```
The original `publicsuffix` library is deprecated and unmaintained. This library is a separate, actively maintained fork.

Quickstart

Initialise the PublicSuffixList object to use the bundled PSL file. Then, use `publicsuffix()` to get the public suffix and `privatesuffix()` to get the registrable domain. The library inherently handles Unicode and Punycode IDNs. Users can also provide their own PSL data.

from publicsuffixlist import PublicSuffixList

psl = PublicSuffixList() # Uses built-in PSL file

# Get the longest public suffix part
print(f"Public Suffix for www.example.com: {psl.publicsuffix('www.example.com')}")
print(f"Public Suffix for www.example.co.uk: {psl.publicsuffix('www.example.co.uk')}")

# Get the shortest domain assigned for a registrant (registrable domain)
print(f"Private Suffix (registrable domain) for www.example.com: {psl.privatesuffix('www.example.com')}")
print(f"Private Suffix (registrable domain) for www.super.example.co.uk: {psl.privatesuffix('www.super.example.co.uk')}")

# Handle domains with unicode characters
print(f"Public Suffix for www.example.香港: {psl.publicsuffix('www.example.香港')}")

# Pass a custom PSL file
# with open('path/to/latest_psl.dat', 'rb') as f:
#     custom_psl = PublicSuffixList(f)

view raw JSON →