Skip to content

typing_extensions: new type hints on older Python

  • What typing_extensions is, and the two jobs it does: backports and previews of accepted typing PEPs.
  • How a library that supports Python 3.10 to 3.14 uses TypeIs, @override, @deprecated, ReadOnly and Self today.
  • Why some names are plain re-exports of typing and others are separate implementations, and why that matters for runtime introspection.
  • How to pin the dependency, when to use version-conditional imports, and when you do not need the package at all.

typing_extensions is a PyPI package, maintained by the Python typing community, that complements the standard-library typing module. It has two purposes: making new type system features available on older Python versions (for example TypeIs, new in typing in Python 3.13), and shipping features from accepted typing PEPs before they reach a CPython release. It also re-exports the rest of typing, so from typing_extensions import X works whatever version added X. The current release is 4.16.0 (July 2, 2026), which supports Python 3.9 and later; the next release drops 3.9.

Type checkers treat typing_extensions.X and typing.X as the same thing, so the package matters mainly at runtime: the import has to succeed on every Python version you support.

The OrdersPortal client SDK supports Python 3.10 through 3.14. Its maintainers want precise narrowing with TypeIs, but that name only exists in typing from Python 3.13. Importing it from typing breaks every user on 3.10 to 3.12.

Running the samples: install the package with python3 -m pip install "typing_extensions>=4.16,<5" and run each script with python3 sample.py. Outputs were produced with CPython 3.10.20 and 3.14.6 and typing_extensions 4.16.0; type-checking output uses mypy 2.4.1 and pyright 1.1.414.

import sys
print("Python", sys.version.split()[0])
try:
from typing import TypeIs # added to typing in Python 3.13
print("typing.TypeIs: available")
except ImportError as exc:
print("typing.TypeIs: ImportError:", str(exc).split(" (")[0])
from typing_extensions import TypeIs # works on every supported version
print("typing_extensions.TypeIs:", TypeIs)

Output on Python 3.10 and on Python 3.14:

Python 3.10.20
typing.TypeIs: ImportError: cannot import name 'TypeIs' from 'typing'
typing_extensions.TypeIs: typing_extensions.TypeIs
Python 3.14.6
typing.TypeIs: available
typing_extensions.TypeIs: typing.TypeIs

On 3.10 the package supplies its own TypeIs; on 3.14 it simply hands back typing.TypeIs. Code written against typing_extensions runs unchanged on both.

For each name, typing_extensions does one of three things depending on the running Python version:

  • Re-export the typing object when the standard library version is complete and correct.
  • Backport: provide its own implementation when typing does not have the name yet.
  • Reimplement a name that typing already has, when a newer PEP or bug fix changed its behavior and the old version’s object lacks it.

This script shows which applies:

import sys
import typing
import typing_extensions
from importlib.metadata import version
print("Python", sys.version.split()[0], "| typing_extensions", version("typing_extensions"))
for name in ["Literal", "Self", "TypeIs", "override", "TypedDict", "TypeAliasType", "sentinel"]:
ext = getattr(typing_extensions, name)
std = getattr(typing, name, None)
if std is None:
where = "backport (not in typing)"
elif ext is std:
where = "re-export of typing." + name
else:
where = "own implementation"
print(f"{name:14} {where}")

Output:

Python 3.10.20 | typing_extensions 4.16.0
Literal re-export of typing.Literal
Self backport (not in typing)
TypeIs backport (not in typing)
override backport (not in typing)
TypedDict own implementation
TypeAliasType backport (not in typing)
sentinel backport (not in typing)
Python 3.14.6 | typing_extensions 4.16.0
Literal re-export of typing.Literal
Self re-export of typing.Self
TypeIs re-export of typing.TypeIs
override re-export of typing.override
TypedDict own implementation
TypeAliasType own implementation
sentinel backport (not in typing)

Even on 3.14, typing_extensions.TypedDict is a different object from typing.TypedDict, because the package already supports TypedDict features from Python 3.15 (PEP 728, closed TypedDicts and typed extra items). sentinel (PEP 661) becomes a built-in in Python 3.15, so it is a backport on every released version.

The practical rule from the package documentation: code that introspects types at runtime should check for both the typing and the typing_extensions object, because whether a name is re-exported can change between releases. Use public helpers such as get_origin() and get_args() instead of private attributes.

The package documentation keeps a full compatibility table. A selection that matters to most codebases:

Name In typing from Use
Self (PEP 673) 3.11 Methods that return their own class
override (PEP 698) 3.12 Fail type checking when an “override” overrides nothing
TypeAliasType (PEP 695) 3.12 Generic aliases without the type statement
TypeIs (PEP 742) 3.13 User-defined narrowing functions
ReadOnly (PEP 705) 3.13 TypedDict keys that must not be reassigned
deprecated (PEP 702) 3.13 (in warnings) Deprecation reported by checkers and at runtime
TypedDict with closed/extra_items (PEP 728) 3.15 Dicts with no unknown keys
TypeForm (PEP 747), disjoint_base (PEP 800) 3.15 Type expressions as values; classes that cannot share a subclass
sentinel (PEP 661) 3.15 (built-in) Unique “missing” markers with a clean repr

Python 3.15 is in development; the 3.15 entries were confirmed against the PEPs (all marked Final for 3.15) and a 3.15.0b4 build.

The OrdersPortal SDK uses five newer features while still supporting Python 3.10. Every import comes from typing_extensions.

"""OrdersPortal client SDK: supports Python 3.10 to 3.14."""
from typing_extensions import ReadOnly, Self, TypedDict, TypeIs, deprecated, override
class OrderDict(TypedDict):
id: ReadOnly[str] # callers may read but not reassign the id
status: str
total: float
def is_order(value: object) -> TypeIs[OrderDict]:
return (
isinstance(value, dict)
and isinstance(value.get("id"), str)
and isinstance(value.get("status"), str)
and isinstance(value.get("total"), (int, float))
)
class OrderQuery:
def __init__(self) -> None:
self.filters: dict[str, str] = {}
def where(self, field: str, value: str) -> Self:
self.filters[field] = value
return self
def describe(self) -> str:
return " AND ".join(f"{k}={v}" for k, v in self.filters.items()) or "all"
class PaidOrderQuery(OrderQuery):
@override
def describe(self) -> str:
return "status=paid AND " + super().describe()
class OrderApiClient:
@deprecated("Use fetch_orders(); get_orders() will be removed in SDK 3.0")
def get_orders(self) -> list[object]:
return self.fetch_orders()
def fetch_orders(self) -> list[object]:
return [{"id": "A-1001", "status": "paid", "total": 98.0}, {"id": 7}]
if __name__ == "__main__":
import sys
print("Python", sys.version.split()[0])
rows = OrderApiClient().fetch_orders()
print([row for row in rows if is_order(row)])
print(PaidOrderQuery().where("region", "EU").describe())

Saved as orders_sdk.py, it prints the same on Python 3.10 and 3.14 (shown for 3.10), and passes mypy --strict --python-version 3.10 and pyright with no errors:

Python 3.10.20
[{'id': 'A-1001', 'status': 'paid', 'total': 98.0}]
status=paid AND region=EU

Self makes PaidOrderQuery().where(...) return PaidOrderQuery, not the base class. An application that misuses the SDK:

from orders_sdk import OrderApiClient, OrderDict, PaidOrderQuery, is_order
from typing_extensions import override
def label(row: object) -> str:
if is_order(row):
return f"{row['id']}: {row['total']:.2f}" # narrowed to OrderDict
return "not an order"
def rename(order: OrderDict) -> None:
order["id"] = "A-9999" # ReadOnly key
class BrokenQuery(PaidOrderQuery):
@override
def describe_all(self) -> str: # overrides nothing
return "all"
OrderApiClient().get_orders() # deprecated

Checked against Python 3.10, and run (both checkers accept label(), because TypeIs narrowed row):

$ mypy --python-version 3.10 --enable-error-code deprecated app.py
app.py:10: error: ReadOnly TypedDict key "id" TypedDict is mutated [typeddict-readonly-mutated]
app.py:14: error: Method "describe_all" is marked as an override, but no base method was found with this name [misc]
app.py:17: error: function orders_sdk.OrderApiClient.get_orders is deprecated: Use fetch_orders(); get_orders() will be removed in SDK 3.0 [deprecated]
Found 3 errors in 1 file (checked 1 source file)
$ pyright app.py
app.py:10:5 - error: Could not assign item in TypedDict
"id" is a read-only key in "OrderDict" (reportTypedDictNotRequiredAccess)
app.py:14:9 - error: Method "describe_all" is marked as override, but no base method of same name is present (reportGeneralTypeIssues)
2 errors, 0 warnings, 0 informations
$ python3 app.py
app.py:17: DeprecationWarning: Use fetch_orders(); get_orders() will be removed in SDK 3.0
OrderApiClient().get_orders() # deprecated

Deprecation reports are opt-in in both checkers: mypy needs --enable-error-code deprecated, and pyright reports it as a warning once reportDeprecated is enabled in its configuration (editors show the call struck through). At runtime, @deprecated emits a DeprecationWarning on every call, on 3.10 and 3.14 alike.

Pin a range, not a version. The package uses semantic versioning since 4.0.0 and promises that names exported by one release keep working in the next. Its documentation recommends typing_extensions >=x.y, <(x+1), where x.y is the first release with every feature you use: here typing_extensions>=4.10,<5 (TypeIs arrived in 4.10.0). An exact pin in a library forces conflicts on every application that installs it.

Drop it when your floor catches up. If you only use names that exist in typing on your oldest supported version, import from typing and remove the dependency. A version-conditional import is a middle ground for applications that want no runtime dependency on newer Pythons:

import sys
if sys.version_info >= (3, 13):
from typing import TypeIs
else:
from typing_extensions import TypeIs
def is_order_id(value: object) -> TypeIs[str]:
return isinstance(value, str) and value.startswith("A-")
print(sys.version_info[:2], TypeIs, is_order_id("A-1001"))

Output on 3.10 and 3.14:

(3, 10) typing_extensions.TypeIs True
(3, 14) typing.TypeIs True

Both mypy and pyright understand sys.version_info checks, so this passed with no errors when checked for 3.10 and for 3.14. You still need typing_extensions installed on Pythons older than 3.13, typically through an environment marker such as typing_extensions>=4.10; python_version<'3.13'.

  • Importing new names from typing in code that supports older Pythons. Your tests on the newest version pass; users on 3.10 get ImportError. Run CI on your oldest supported version.
  • Assuming typing_extensions.X is typing.X. Runtime checks such as get_origin(tp) is typing.Literal can fail when the package returns its own implementation; compare against both.
  • Exact or missing version pins. typing_extensions==4.9.0 in a library blocks upgrades for everyone; no lower bound lets an old release without the name you need be installed.
  • Pairing a new qualifier with an old base. On Python 3.10, a typing.TypedDict subclass with an id: ReadOnly[str] field has no __readonly_keys__ at runtime; the same class based on typing_extensions.TypedDict reports frozenset({'id'}). Import TypedDict from the same place as its qualifiers.
Situation Recommendation
Library supporting older Pythons than the feature needs Import from typing_extensions, pin >=x.y,<5
Using an accepted PEP before its CPython release (for example PEP 728) typing_extensions is the only way
Application pinned to Python 3.14 using only 3.14 names Import from typing; no dependency needed
Want no runtime dependency on new Pythons sys.version_info conditional import plus an environment marker
Runtime introspection of type objects Accept both typing and typing_extensions objects

typing_extensions 4.16.0 (July 2, 2026) requires Python 3.9 or later and supports Python 3.15; the next release drops 3.9, and old versions are dropped some time after their end of life. Feature releases (4.N.0) follow at least one release candidate; bug-fix releases are 4.N.1 and up. Versions before 4.0.0 were numbered after the Python version they mirrored (for example 3.10.0.0).

1. Why import TypeIs from typing_extensions instead of typing? typing.TypeIs exists only on Python 3.13 and later. Importing it from typing_extensions works on every Python version the package supports, and on 3.13+ it returns the same typing.TypeIs object, so there is no cost on newer versions.

2. How should a library declare its dependency on typing_extensions? With a lower bound at the first release containing every feature it uses and an upper bound below the next major version, for example typing_extensions>=4.10,<5, optionally with an environment marker that limits it to older Pythons. The project’s semantic-versioning policy makes that range safe.

3. Senior scenario: your framework inspects user models at runtime to build JSON schemas. A user reports that ReadOnly fields are ignored on Python 3.12 but work on 3.13. How do you investigate and fix it? On 3.12 the user’s ReadOnly (and possibly TypedDict) comes from typing_extensions, while the framework probably compares against typing.ReadOnly or reads a private attribute that only the 3.13 implementation sets. Reproduce on both versions, then switch the framework to the documented approach: resolve names against both modules (the package docs show a cached is_typing_name helper), use get_origin/get_args and the public __readonly_keys__/__mutable_keys__ attributes, and add CI jobs for each supported Python version with both import sources.

  • typing_extensions backports new typing features to older Pythons and ships accepted PEPs before their CPython release.
  • Checkers treat its names like the typing ones; the value is that imports work at runtime everywhere.
  • Some names are re-exports, some are separate implementations, and that can change between releases: introspection code must handle both.
  • Pin >=x.y,<5, test on your oldest supported Python, and drop the dependency when your minimum version has everything you need.
  • 4.16.0 is current and already carries Python 3.15 features such as sentinel, closed TypedDicts and TypeForm.