{"id":5248,"library":"hstspreload","title":"Chromium HSTS Preload List Python Package","description":"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.","status":"active","version":"2025.1.1","language":"en","source_language":"en","source_url":"https://github.com/sethmlarson/hstspreload","tags":["security","HSTS","network","web security","preload list","HTTPS"],"install":[{"cmd":"pip install hstspreload","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"in_hsts_preload","correct":"from hstspreload import in_hsts_preload"}],"quickstart":{"code":"import idna\nfrom hstspreload import in_hsts_preload\n\ndef check_hsts_preload(hostname):\n    # Ensure the hostname is IDNA-encoded for internationalized domain names\n    # For ASCII domains, this step typically returns the original hostname.\n    encoded_hostname = idna.encode(hostname).decode('ascii')\n    is_preloaded = in_hsts_preload(encoded_hostname)\n    print(f\"Is '{hostname}' (IDNA: '{encoded_hostname}') on the HSTS preload list? {is_preloaded}\")\n\n# Example usage\ncheck_hsts_preload('google.com')\ncheck_hsts_preload('example.com') # Often not preloaded for general use\ncheck_hsts_preload('bücher.example') # Internationalized Domain Name (IDN)","lang":"python","description":"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`."},"warnings":[{"fix":"Ensure hostnames are IDNA-encoded before passing them to `in_hsts_preload()`. Example: `idna.encode('bücher.example').decode('ascii')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"If consistency across all browsers is critical, consult browser-specific documentation or testing tools in addition to this library.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use hstspreload.org for validating preloading eligibility and configuration issues. This library is for querying the list state, not for site configuration analysis.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}