Registry / http-networking / hstspreload

hstspreload

library2025.1.1pypypi✓ verified 22d ago

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.

http-networking auth-security

pip install hstspreload

github ↗package ↗

INSTALL

IMPORT

SIG · HSTSPRELOAD

hstspreload

http-networkingpythonv2025.1.1

Install

1.7s avg

Import

51ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2025.1.1 · 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.054s · 20.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.048s · 21MB

18MB installed

● package 18MB

Code

Verified usage

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

in_hsts_preload

✓ from hstspreload import in_hsts_preload

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)

hstspreload --version

Debug

Known issues

gotchaThe `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')`.

affects: All versions

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

affects: All versions

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'hstspreload'

The 'hstspreload' package has not been installed in your Python environment.

fix

pip install hstspreload

AttributeError: module 'hstspreload' has no attribute 'get_hsts_data'

You are attempting to call a non-existent function or access an internal data structure not exposed by the public API. The primary function for querying is `in_hsts_preload()`.

fix

from hstspreload import in_hsts_preload
is_preloaded = in_hsts_preload('example.com')

Incorrect results for internationalized domain names (IDNs)

Internationalized domain names (IDNs) must be IDNA-encoded before being passed to the `in_hsts_preload()` function to ensure correct lookup.

fix

import idna
hostname = 'bücher.example'
encoded_hostname = idna.encode(hostname).decode('ascii')
is_preloaded = in_hsts_preload(encoded_hostname)

TypeError: in_hsts_preload() missing 1 required positional argument: 'host'

The `in_hsts_preload` function was called without providing the required hostname argument.

fix

from hstspreload import in_hsts_preload
is_preloaded = in_hsts_preload('example.com')

Upgrade

Version history

2025.1.1latest on PyPI · released Jan 1, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sethmlarson/hstspreload ↗

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