Python TypedDict: Defining Type-Safe Dictionaries
Learn how to use Python's TypedDict to declare dictionary shapes for static type checkers, improving type safety and maintainability.

When you need to pass a dictionary with a fixed set of keys and known value types, Python's TypedDict from the typing module lets you describe that shape for static type checkers without changing runtime behavior. Unlike a plain dict annotation or a custom class, TypedDict declares the expected keys and value types so type checkers can catch missing keys, wrong value types, and accidental key renames before the code runs.
Defining a TypedDict
A TypedDict is defined as a class that inherits from typing.TypedDict. Each attribute annotation declares a key and its value type. For example, a user record might look like this:
from typing import TypedDict
class User(TypedDict):
id: int
name: str
email: strThis definition tells static type checkers that a User dictionary must contain those declared keys, with the specified value types. By default, all declared keys are required. You can also use the functional syntax, which is useful when you want to build the type dynamically:
from typing import TypedDict
User = TypedDict('User', {'id': int, 'name': str, 'email': str})Both forms are equivalent. The class-based syntax is more readable and supports inheritance, which we will cover later.
Using TypedDict in Functions
Once you have a TypedDict, you can use it as a type hint for function parameters and return values. This makes the expected dictionary structure explicit at the call site.
def send_welcome_email(user: User) -> None:
print('Sending email to ' + user['email'])
def create_user(id: int, name: str) -> User:
return {'id': id, 'name': name, 'email': f'{name.lower()}@example.com'}When you call create_user, the type checker verifies that the returned dictionary matches the User shape. If you later try to access a key that is not defined, like user['phone'], the type checker reports an error. This catches many bugs that would otherwise only surface at runtime.
Runtime Behavior: TypedDict Is Just a Dictionary
TypedDict is a type-hint construct, not a runtime validation class. Objects annotated with it are ordinary dict objects, and the class definition is not used to validate keys or values at runtime. In particular, isinstance() checks are not supported for TypedDict types.
user = {'id': 1, 'name': 'Alice', 'email': 'alice@example.com'}
print(type(user)) # <class 'dict'>Because of this, TypedDict is ideal for data that crosses system boundaries, such as JSON payloads, database rows, or configuration files. The structure is known in advance, but the data itself is naturally represented as a dictionary. If you need runtime validation, consider using a library like Pydantic or a dataclass with custom validation.
Type Checking with mypy and Other Tools
TypedDict is fully supported by mypy, pyright, and the type checker built into most IDEs. To get the benefit, you must run a type checker as part of your development workflow. For example, with mypy, you can run:
mypy your_module.pyIf you try to assign a value of the wrong type, mypy will flag it. Consider this function:
def update_email(user: User, new_email: str) -> None:
user['email'] = new_emailIf you accidentally pass an integer as new_email, mypy will report an error. The same applies when you construct a dictionary that is missing a required key or includes an extra key. This static analysis is the primary value of TypedDict.
Common Mistakes and How to Avoid Them
One common mistake is relying on TypedDict at runtime. TypedDict is a static type hint, not a runtime validator: isinstance() checks are not supported, and malformed dictionaries will not raise errors when assigned. Build the dictionary as you normally would, then let the type checker verify the shape in your editor or CI.
Another common mistake is forgetting that all keys are required by default. If you have optional fields, you must mark them with total=False:
class User(TypedDict, total=False):
id: int
name: str
email: str
phone: str # optionalWith total=False, every key becomes optional. You can also mix required and optional keys by using inheritance:
class BaseUser(TypedDict):
id: int
name: str
class FullUser(BaseUser, total=False):
email: str
phone: strHere, id and name are required, while email and phone are optional. This pattern is useful when you have a core set of fields that must always exist and additional fields that may be present.
TypedDict vs Dataclasses vs NamedTuple
When you need a structured data container, you have several options. TypedDict is best when you want to work with dictionary-like data, especially JSON. Dataclasses and NamedTuple create actual classes with attribute access and can carry methods, but they are not dictionaries, so they need conversion for JSON serialization. They also do not perform runtime type validation by default.
| Feature | TypedDict | Dataclass | NamedTuple |
|---|---|---|---|
| Runtime type | dict | custom class | tuple subclass |
| Access style | user['name'] | user.name | user.name |
| Runtime validation | None | None (unless coded) | None |
| JSON serialization | Direct | Needs conversion | Needs conversion |
| Best for | JSON-like data | Domain objects | Lightweight records |
If your data comes from a JSON API and you only need type safety during development, TypedDict is the simplest choice. If you need to attach methods or perform validation, a dataclass is more appropriate. NamedTuple is useful for immutable records with a small number of fields.
Production Considerations and Maintainability
In a large codebase, TypedDict helps keep the shape of data contracts consistent. When an API response changes, you update the TypedDict definition, and the type checker immediately shows every place that uses the old shape. This is far more reliable than searching for dictionary keys manually.
One operational concern is that TypedDict does not protect against runtime errors from malformed data, such as a missing key in a response from an external service. If you are working with untrusted input, you still need runtime validation. You can combine TypedDict with a validation library that reads the type hints, but that is beyond the scope of the type hint itself.
Another maintainability aspect is that TypedDict definitions can be reused across modules. If multiple functions operate on the same dictionary shape, define the TypedDict in a shared module and import it. This avoids duplication and ensures that changes are propagated consistently.
Finally, be aware that TypedDict is not a runtime performance optimization. It adds no runtime overhead; operations on the resulting dictionaries are the same as on plain dict objects. The benefit is in development time and code clarity.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.