Registry / http-networking / publicsuffixlist

publicsuffixlist

library1.0.2.20260821pypypi✓ verified 25d ago

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.

http-networking serialization

pip install publicsuffixlist

github ↗package ↗

INSTALL

IMPORT

SIG · PUBLICSUFFIXLIST

publicsuffixlist

http-networkingpythonv1.0.2.20260821

Install

1.6s avg

Import

11ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.2.20260821 · 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.012s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.008s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

PublicSuffixList

✓ from publicsuffixlist import PublicSuffixList

✗ from publicsuffix import PublicSuffixList

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

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)

publicsuffixlist --version

Debug

Known issues

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

affects: All versions

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

affects: All versions

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

affects: All versions

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

affects: Users migrating from `publicsuffix`

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'publicsuffixlist'

The `publicsuffixlist` package has not been installed in your Python environment or is not accessible.

fix

Install the package using pip: `pip install publicsuffixlist`

TypeError: expected string or bytes-like object

Methods like `publicsuffix()` or `privatesuffix()` were called with an argument that is not a string or bytes-like object (e.g., an integer or None).

fix

Ensure the input passed to the `publicsuffix` or `privatesuffix` methods is always a string or bytes-like object: `psl.publicsuffix('example.com')`

AttributeError: 'NoneType' object has no attribute '...' (e.g., 'lower')

This error occurs when methods like `publicsuffix()` or `privatesuffix()` return `None` (indicating no public or private suffix was found for the given input, or the input was invalid), and you attempt to call a string method (like `.lower()` or `.split()`) on the `None` result without checking for it.

fix

Always check if the result of `publicsuffix()` or `privatesuffix()` is `None` before attempting further operations: `result = psl.publicsuffix('com'); if result: print(result.lower())`

AttributeError: module 'publicsuffixlist' has no attribute 'PublicSuffixList'

This typically happens when you use `import publicsuffixlist` and then try to access `publicsuffixlist.PublicSuffixList` instead of correctly importing the class directly.

fix

Import the `PublicSuffixList` class directly using `from publicsuffixlist import PublicSuffixList` and then instantiate it as `psl = PublicSuffixList()`

Upgrade

Version history

1.0.2.20260821latest on PyPI · released Aug 21, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.5 or newer.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/ko-zu/psl ↗

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