Install & Compatibility
Where this runs
tested against v3.7.4.3 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.009s · 65.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.0s · import 0.006s · 20MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
List
✓ from typing import List
✗ from collections.abc import List
While built-in generics (list[int]) are preferred in Python 3.9+, using `typing.List` is correct for broader compatibility (Python 3.5-3.8 and the backport package). `collections.abc.List` is a runtime type, not typically used for type hints directly.
Dict
✓ from typing import Dict
Same reasoning as List.
Optional
✓ from typing import Optional
Union
✓ from typing import Union
Callable
✓ from typing import Callable
✗ from collections.abc import Callable
For type hints, `typing.Callable` is standard. `collections.abc.Callable` is for runtime checks, but `typing.Callable` itself is deprecated in favor of `collections.abc.Callable` in some contexts for runtime checking if strict runtime compatibility is needed. However, for type hint *annotations*, `typing.Callable` is typically what's imported.
Any
✓ from typing import Any
This quickstart demonstrates basic type hinting using common constructs from the `typing` module, including type annotations for variables, function parameters, and return values. It also shows the use of `List`, `Optional`, and `Union` types for more complex scenarios. The `from __future__ import annotations` import is recommended for broader compatibility and allows for 'postponed evaluation' of type annotations.
from __future__ import annotations # For Python < 3.9, enables future syntax for type hints
from typing import List, Union, Optional
def greet(name: str) -> str:
return f"Hello, {name}!"
def get_item(items: List[str], index: int) -> Optional[str]:
if 0 <= index < len(items):
return items[index]
return None
def process_value(value: Union[int, str]) -> str:
if isinstance(value, int):
return f"Received an integer: {value}"
return f"Received a string: {value}"
print(greet("Alice"))
print(get_item(["apple", "banana"], 0))
print(get_item(["apple", "banana"], 2))
print(process_value(123))
print(process_value("hello"))
Debug
Known issues
gotchaInstalling the `typing` PyPI package on Python 3.5 or later has *no effect* because the standard library `typing` module takes precedence. In some scenarios (e.g., `pip install -t . typing`), it can even cause `AttributeError` by shadowing the standard library module.fixFor Python 3.5+, do not install the `typing` PyPI package. Rely on the built-in `typing` module. For libraries supporting older Pythons, use conditional installation (`pip install "typing; python_version < '3.5'"`).
affects: Python >= 3.5
deprecatedFor built-in generic types like `list`, `dict`, `set`, and `tuple`, using their `typing` module counterparts (e.g., `typing.List`, `typing.Dict`) is deprecated since Python 3.9.fixUse the built-in generics directly, e.g., `list[str]` instead of `typing.List[str]`, and `dict[str, int]` instead of `typing.Dict[str, int]`.
affects: Python >= 3.9
gotchaType hints are primarily for static analysis tools (type checkers like MyPy, IDEs) and are *not* enforced by the Python runtime by default. Incorrect type hints will not cause runtime errors but will be flagged by static analyzers.fixIntegrate a static type checker into your development workflow (e.g., MyPy, Pyright) to leverage the benefits of type hints.
affects: All Python versions
deprecated`typing.Callable` is deprecated for runtime type checking in some contexts. While still commonly used for type annotations, `collections.abc.Callable` may be preferred for runtime checks where strict compatibility is desired, or when working with `isinstance` checks.fixConsider using `collections.abc.Callable` for runtime checks. For annotations, `typing.Callable` remains broadly understood but be aware of the shift.
affects: Python >= 3.9 (for deprecation awareness)
breaking`typing.NewType` changed from a function to a class in Python 3.10, which introduced a slight runtime overhead. This change was reverted in Python 3.11, restoring performance to Python 3.9 levels. Code relying on the exact type or performance of `NewType` instantiation in 3.10 could be affected.fixUpgrade to Python 3.11+ if `NewType` performance or its class-based nature in 3.10 is an issue.
affects: Python 3.10
gotchaRelying on internal `typing` module attributes (e.g., `__union_params__`) prior to Python 3.8 was risky due to the module's provisional status and led to breaking changes. Public APIs like `get_args()` were introduced to provide stable access.fixAvoid using undocumented internal attributes of the `typing` module. Use stable public APIs like `typing.get_args()` and `typing.get_origin()` when inspecting types at runtime.
affects: Python < 3.8
Errors
Common errors & fixes
NameError: name 'List' is not defined
Type hints like `List`, `Dict`, `Tuple`, `Set`, and `Optional` are not built-in types and must be explicitly imported from the `typing` module.
fixAdd the necessary import statement: `from typing import List` (or `Dict`, `Tuple`, etc., as needed).
TypeError: 'type' object is not subscriptable
In Python versions before 3.9, built-in types like `list` or `dict` cannot be directly subscripted (e.g., `list[str]`) for type hinting; you must use their capitalized counterparts imported from the `typing` module.
fixImport the capitalized generic type from `typing` and use it for hinting. For example, use `from typing import List; my_list: List[str]` instead of `my_list: list[str]`.
AttributeError: module 'typing' has no attribute 'Protocol'
You are attempting to use a `typing` feature (such as `Protocol`, `TypedDict`, `Literal`, `TypeAlias`, or `Self`) that was introduced in a newer Python version than your current interpreter supports, and it's not available in your `typing` module or the installed `typing` backport package is too old.
fixUpgrade your Python interpreter to a version that includes the desired feature (e.g., Python 3.8+ for `Protocol`, Python 3.10+ for `TypeAlias`, Python 3.11+ for `Self`). If you are on Python versions older than 3.5, ensure the `typing` PyPI package is installed and up-to-date (`pip install --upgrade typing`). For newer features on intermediate Python versions (3.5-3.7/8), you might need to install `typing_extensions`.
ModuleNotFoundError: No module named 'typing'
The `typing` module is not found because it became part of Python's standard library only from version 3.5 onwards. For Python versions older than 3.5, the `typing` backport package must be explicitly installed.
fixInstall the `typing` backport package using pip: `pip install typing`
AttributeError: module 'typing' has no attribute 'Literal'
This happens when attempting to use a type hint feature (e.g., `Literal`, `ParamSpec`, `TypeGuard`, `Self`) that was introduced in a newer Python version than the interpreter being used.
fixInstall the `typing_extensions` package (`pip install typing_extensions`) and import the feature from there (e.g., `from typing_extensions import Literal`), or upgrade your Python interpreter to a version where the feature is built-in.
Upgrade
Version history
3.10.0.0latest on PyPI · released May 1, 2021
Audit
Dependencies
No dependency data recorded yet.