typing_extensions: new type hints on older Python
What you’ll learn
Section titled “What you’ll learn”- What
typing_extensionsis, 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,ReadOnlyandSelftoday. - Why some names are plain re-exports of
typingand 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.
Summary
Section titled “Summary”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 problem it solves
Section titled “The problem it solves”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 versionprint("typing_extensions.TypeIs:", TypeIs)Output on Python 3.10 and on Python 3.14:
Python 3.10.20typing.TypeIs: ImportError: cannot import name 'TypeIs' from 'typing'typing_extensions.TypeIs: typing_extensions.TypeIsPython 3.14.6typing.TypeIs: availabletyping_extensions.TypeIs: typing.TypeIsOn 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.
How it works
Section titled “How it works”For each name, typing_extensions does one of three things depending on the running Python version:
- Re-export the
typingobject when the standard library version is complete and correct. - Backport: provide its own implementation when
typingdoes not have the name yet. - Reimplement a name that
typingalready 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 sysimport typingimport typing_extensionsfrom 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.0Literal re-export of typing.LiteralSelf backport (not in typing)TypeIs backport (not in typing)override backport (not in typing)TypedDict own implementationTypeAliasType backport (not in typing)sentinel backport (not in typing)
Python 3.14.6 | typing_extensions 4.16.0Literal re-export of typing.LiteralSelf re-export of typing.SelfTypeIs re-export of typing.TypeIsoverride re-export of typing.overrideTypedDict own implementationTypeAliasType own implementationsentinel 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.
What it provides
Section titled “What it provides”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.
Realistic example
Section titled “Realistic example”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=EUSelf makes PaidOrderQuery().where(...) return PaidOrderQuery, not the base class. An application that misuses the SDK:
from orders_sdk import OrderApiClient, OrderDict, PaidOrderQuery, is_orderfrom 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() # deprecatedChecked against Python 3.10, and run (both checkers accept label(), because TypeIs narrowed row):
$ mypy --python-version 3.10 --enable-error-code deprecated app.pyapp.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.pyapp.py:17: DeprecationWarning: Use fetch_orders(); get_orders() will be removed in SDK 3.0 OrderApiClient().get_orders() # deprecatedDeprecation 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.
Production patterns
Section titled “Production patterns”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 TypeIselse: 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 TrueBoth 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'.
Common mistakes
Section titled “Common mistakes”- Importing new names from
typingin code that supports older Pythons. Your tests on the newest version pass; users on 3.10 getImportError. Run CI on your oldest supported version. - Assuming
typing_extensions.X is typing.X. Runtime checks such asget_origin(tp) is typing.Literalcan fail when the package returns its own implementation; compare against both. - Exact or missing version pins.
typing_extensions==4.9.0in 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.TypedDictsubclass with anid: ReadOnly[str]field has no__readonly_keys__at runtime; the same class based ontyping_extensions.TypedDictreportsfrozenset({'id'}). ImportTypedDictfrom the same place as its qualifiers.
When to use it and when not to
Section titled “When to use it and when not to”| 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 |
Compatibility
Section titled “Compatibility”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).
Interview questions
Section titled “Interview questions”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.
Key takeaways
Section titled “Key takeaways”typing_extensionsbackports newtypingfeatures to older Pythons and ships accepted PEPs before their CPython release.- Checkers treat its names like the
typingones; 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 andTypeForm.
Related pages
Section titled “Related pages”- Python type hints: checkers, narrowing and the core constructs used here.
- Python type hints basics: annotation syntax step by step.
- Protocols: structural typing, available from
typingsince 3.8. - Python modules and packages: imports and installing packages.
- Python tools: the tooling around a typed codebase.
Official references
Section titled “Official references”- typing_extensions documentation and source and changelog (4.16.0)
- typing_extensions 4.16.0 on PyPI
- Python 3.14
typingmodule - Python 3.14
warnings.deprecated - Typing specification (typing.python.org)
- PEP 742: Narrowing types with TypeIs, PEP 698: Override decorator, PEP 702: Marking deprecations, PEP 705: TypedDict read-only items
- PEP 728: TypedDict with typed extra items and PEP 661: Sentinel values (Python 3.15)