typing-extensions

4.15.0 · active · verified Fri Mar 27

typing-extensions provides backported and experimental type hints for Python, serving two purposes: enabling use of new type system features on older Python versions (e.g., TypeGuard from 3.10 is available on 3.9+), and enabling experimentation with new PEP-proposed typing constructs before they land in the standard library. The library also re-exports all names from the standard typing module, so it can serve as a single import source. Current version is 4.15.0 (as of early 2026); feature releases follow an irregular cadence under Semantic Versioning where only the major version is bumped for breaking changes.

Warnings

breaking Python 3.8 support dropped in 4.14.0. Projects that still run on CPython/PyPy 3.8 must pin to typing_extensions<4.14.
Fix: Pin `typing-extensions~=4.13` for Python 3.8 environments, or upgrade Python.
breaking typing.ByteString is not re-exported and is removed in Python 3.14. Any code that relied on typing_extensions re-exporting ByteString will break.
Fix: Replace `typing.ByteString` or `typing_extensions.ByteString` with `typing_extensions.Buffer` (equivalent to `collections.abc.Buffer` on 3.12+).
breaking TypedDict keyword-argument construction syntax (e.g., `Movie = TypedDict('Movie', title=str)`) emits DeprecationWarning on Python 3.12 and raises TypeError on Python 3.13+.
Fix: Use the class-based TypedDict syntax: `class Movie(TypedDict): title: str`.
breaking typing_extensions does not re-export names removed from typing, including the anticipated removal of `typing.no_type_check_decorator` in Python 3.15. Importing it from typing_extensions will raise ImportError on 4.14+.
Fix: Stop using `no_type_check_decorator`; it is unsupported by type checkers and has no maintained replacement.
gotcha Pinning to `typing-extensions~=x.y.z` (patch-level) defeats Semantic Versioning and can block important bugfixes. The correct specifier is `typing-extensions~=x.y` (minor-level) or `>=x.y,<(x+1)`.
Fix: Use `typing-extensions~=4.14` (or whichever minor first includes your needed features), not `==4.14.1`.
gotcha When introspecting types at runtime (e.g., `isinstance(obj, some_protocol)`), always check for both `typing.X` and `typing_extensions.X` variants. Future releases may re-export a separate backport version that is not `is`-identical to the stdlib one.
Fix: Use `isinstance(obj, (typing.X, typing_extensions.X))` or compare with `in (typing.X, typing_extensions.X)` in runtime isinstance/issubclass guards.
gotcha `deprecated` (PEP 702) was added in 4.5.0 but many ecosystems (FastAPI, Pydantic) require >=4.8.0. Environments with conda-pinned or transitive older typing_extensions produce `ImportError: cannot import name 'deprecated'`.
Fix: Ensure `typing-extensions>=4.8.0` is in your dependency list; audit layered environments (Docker layers, conda + pip) for duplicate installs at different versions.

Install

pip install typing-extensions Latest
pip install 'typing-extensions~=4.15' Pinned minor (recommended)

Imports

TypedDict
```
from typing_extensions import TypedDict
```
typing_extensions version has additional features (ReadOnly, closed/extra_items via PEP 728) and bug fixes not present in the stdlib version on older Python releases. Prefer typing_extensions.TypedDict when targeting <3.13 for full feature parity.
Annotated
```
from typing_extensions import Annotated
```
Safe to import from typing_extensions on all supported versions; re-exported from stdlib typing internally.
Protocol
```
from typing_extensions import Protocol
```
typing_extensions.Protocol has backported isinstance() fixes and allows @runtime_checkable interop. On Python <3.12 the stdlib version has known isinstance() performance and correctness issues.
Self
```
from typing_extensions import Self
```
Backport of PEP 673; available in stdlib typing only from Python 3.11.
TypeAlias
```
from typing_extensions import TypeAlias
```
Backport of PEP 613; in stdlib from Python 3.10. Use typing_extensions version for Python 3.9 compatibility.
TypeAliasType
```
from typing_extensions import TypeAliasType
```
Backport of PEP 695 type alias syntax; native only in Python 3.12+.
TypeGuard
```
from typing_extensions import TypeGuard
```
Backport of PEP 647; in stdlib from Python 3.10. Consider TypeIs (PEP 742, 4.10+) for more intuitive narrowing semantics.
TypeIs
```
from typing_extensions import TypeIs
```
Added in 4.10.0 (PEP 742). Prefer over TypeGuard for most narrowing use-cases — TypeIs has stricter but more predictable semantics.
override
```
from typing_extensions import override
```
Backport of PEP 698; in stdlib from Python 3.12. Decorator sets .__override__ = True at runtime.
deprecated
```
from typing_extensions import deprecated
```
Backport of PEP 702 (added in 4.5.0). Raises DeprecationWarning at call site. Was a common ImportError source when frameworks (FastAPI, Pydantic) required >=4.8.0 but environments had older pinned versions.
get_annotations
```
from typing_extensions import get_annotations
```
Added in 4.13.0. Backport of inspect.get_annotations with PEP 649 features. Do not use inspect.get_annotations directly if you need PEP 649 lazy evaluation semantics.
evaluate_forward_ref
```
from typing_extensions import evaluate_forward_ref
```
Added in 4.13.0. Use instead of typing.get_type_hints() when you need fine-grained ForwardRef evaluation control under PEP 649.
Buffer
```
from typing_extensions import Buffer
```
typing.ByteString is deprecated and removed in Python 3.14. Use typing_extensions.Buffer for buffer-protocol types instead.
LiteralString
```
from typing_extensions import LiteralString
```
Backport of PEP 675; in stdlib from Python 3.11.
Never
```
from typing_extensions import Never
```
Backport of typing.Never (3.11+). Prefer over NoReturn for non-return-type positions.

Quickstart

Demonstrates the most commonly used constructs: TypedDict with ReadOnly/NotRequired fields, TypeAlias, Self, runtime_checkable Protocol, TypeIs narrowing, the @deprecated decorator, and @override.

from typing_extensions import (
    TypedDict,
    NotRequired,
    ReadOnly,
    Annotated,
    Self,
    TypeAlias,
    override,
    deprecated,
    TypeIs,
    Protocol,
    runtime_checkable,
)
import sys

# TypedDict with optional and read-only fields (PEP 655, PEP 705)
class Movie(TypedDict):
    title: ReadOnly[str]
    year: NotRequired[int]

movie: Movie = {"title": "Blade Runner"}

# TypeAlias for clarity
Vector: TypeAlias = list[float]

# Self in method signatures
class Builder:
    def set_name(self, name: str) -> Self:
        self.name = name
        return self

# Protocol with runtime checking
@runtime_checkable
class Drawable(Protocol):
    def draw(self) -> None: ...

# TypeIs for narrowing
def is_str_list(val: list[object]) -> TypeIs[list[str]]:
    return all(isinstance(x, str) for x in val)

# deprecated decorator
@deprecated("Use new_api() instead")
def old_api() -> None:
    pass

# override for subclass safety
class Base:
    def compute(self) -> int:
        return 0

class Child(Base):
    @override
    def compute(self) -> int:
        return 42

print(f"typing_extensions quickstart OK — Python {sys.version}")

view raw JSON →