Install & Compatibility
Where this runs
tested against v0.6.0.20260827 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lookup
✓ from webencodings_stubs import lookup
✗ from webencodings-stubs import lookup
This example demonstrates how to use the 'webencodings' library with type hints. After installing both `webencodings` and `types-webencodings`, a type checker like Mypy will use the stubs to validate the type annotations in the code. The `lookup` function and `Encoding` type are imported directly from `webencodings`, not `types_webencodings`.
import sys
from webencodings import lookup, Encoding
def get_encoding_name(label: str) -> str | None:
"""Looks up an encoding label and returns its canonical name, if found."""
encoding: Encoding | None = lookup(label)
if encoding:
return encoding.name
return None
if __name__ == "__main__":
# Example usage
utf8_name = get_encoding_name("utf-8")
print(f"'utf-8' canonical name: {utf8_name}")
unknown_name = get_encoding_name("not-an-encoding")
print(f"'not-an-encoding' canonical name: {unknown_name}")
# To type-check this code, save it as `main.py` and run:
# pip install mypy webencodings types-webencodings
# mypy main.py
Debug
Known issues
gotchaInstalling `types-webencodings` does not provide the runtime functionality of the `webencodings` library. It only provides type stubs for static analysis. You must install `webencodings` separately if you intend to run the code.fixAlways install `webencodings` alongside `types-webencodings` if your application uses 'webencodings' at runtime: `pip install webencodings types-webencodings`.
affects: All versions
gotchaDo not attempt to import symbols directly from `types_webencodings` (e.g., `from types_webencodings import lookup`). Type stub packages are not designed to be imported at runtime. Imports should always target the actual runtime library, `webencodings`.fixImport all symbols from the runtime package: `from webencodings import ...`.
affects: All versions
gotchaThe versioning scheme for `types-*` packages from Typeshed is `X.Y.Z.YYYYMMDD`. The `X.Y.Z` typically corresponds to the version of the runtime package (`webencodings`) the stubs are targeting, while `YYYYMMDD` indicates the release date of the stub package from Typeshed. Incompatibility can occur if the stub package version `X.Y.Z` significantly diverges from your installed `webencodings` version.fixConsider pinning the `types-webencodings` version to match the major and minor version of your `webencodings` dependency (e.g., `webencodings==0.5.1` and `types-webencodings==0.5.*`). Alternatively, manage stub versions carefully to avoid unexpected type-checking errors with new runtime library releases.
affects: All versions
breakingWhile Typeshed aims to minimize breaking changes, any update to a stub package can introduce changes that might cause your code to fail type checking, even if the runtime behavior of 'webencodings' hasn't changed. This is inherent to the nature of static typing.fixRun your type checker (e.g., Mypy, Pyright) as part of your CI/CD pipeline and review any new type errors when updating `types-webencodings`. Pinning stub versions (`types-webencodings==X.Y.Z.YYYYMMDD`) can prevent unexpected type errors but may mean missing out on improved type fidelity.
affects: All versions, particularly when updating to new `types-webencodings` releases.
Upgrade
Version history
0.6.0.20260827latest on PyPI · released Aug 27, 2026
Audit
Dependencies
webencodingsrequiredThis is a stub-only package; the 'webencodings' library is required at runtime for actual functionality.