Chromium HSTS Preload List Python Package

2025.1.1 · active · verified Mon Apr 13

The `hstspreload` Python package provides an offline, queryable version of the Chromium HSTS (HTTP Strict Transport Security) preload list. It allows users to check if a given hostname is included in this list, indicating that web browsers should only access it via HTTPS. The package's data is updated monthly by an automated script, ensuring a regularly refreshed snapshot of the official list.

Warnings

gotcha The `in_hsts_preload()` function expects an IDNA-encoded hostname (e.g., `xn--domain-name`). Supplying a Unicode domain name directly (e.g., `bücher.example`) without encoding it first will lead to incorrect or unexpected results. Use Python's built-in `str.encode('idna').decode('ascii')` method or the `idna` PyPI package (if extended IDNA functionality is needed) to properly encode hostnames.
Fix: Ensure hostnames are IDNA-encoded before passing them to `in_hsts_preload()`. Example: `idna.encode('bücher.example').decode('ascii')`.
gotcha The package's HSTS preload list data is generated and updated monthly via an automated script. This means the list is not real-time and may be slightly out of sync with the absolute latest changes on the Chromium HSTS preload list (hstspreload.org).
Fix: Be aware of the monthly update cycle. For applications requiring the absolute latest state, consider monitoring the Chromium repository directly or manually triggering a package update if available for critical changes.
gotcha This library specifically checks against the *Chromium HSTS preload list*. While this list is widely adopted by other major browsers (e.g., Firefox, Edge, Safari), discrepancies may exist with other browser-specific preload lists or their update cadences. Results from `hstspreload` may not perfectly reflect the HSTS behavior of all browser environments.
Fix: If consistency across all browsers is critical, consult browser-specific documentation or testing tools in addition to this library.
gotcha The `hstspreload` library's sole purpose is to check if a domain is *already on* the HSTS preload list. It does *not* validate whether a domain *meets the requirements* for HSTS preloading (e.g., correct HSTS header, valid SSL certificate, HTTPS redirects, `max-age` directive). For comprehensive preloading eligibility checks, use the official hstspreload.org website.
Fix: Use hstspreload.org for validating preloading eligibility and configuration issues. This library is for querying the list state, not for site configuration analysis.

Install

pip install hstspreload Install with pip

Imports

in_hsts_preload
```
from hstspreload import in_hsts_preload
```

Quickstart

This quickstart demonstrates how to import and use the `in_hsts_preload` function to check if a hostname is on the HSTS preload list. It includes an important step for IDNA encoding to correctly handle internationalized domain names (IDNs) like `bücher.example`.

import idna
from hstspreload import in_hsts_preload

def check_hsts_preload(hostname):
    # Ensure the hostname is IDNA-encoded for internationalized domain names
    # For ASCII domains, this step typically returns the original hostname.
    encoded_hostname = idna.encode(hostname).decode('ascii')
    is_preloaded = in_hsts_preload(encoded_hostname)
    print(f"Is '{hostname}' (IDNA: '{encoded_hostname}') on the HSTS preload list? {is_preloaded}")

# Example usage
check_hsts_preload('google.com')
check_hsts_preload('example.com') # Often not preloaded for general use
check_hsts_preload('bücher.example') # Internationalized Domain Name (IDN)

view raw JSON →