Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readPython
#typing#dictionaries#type hints#mypy
Illustration of a Python dictionary with type annotations for keys and values, representing a typed dict.

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:

python
from typing import TypedDict class User(TypedDict): id: int name: str email: str

This 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:

python
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.

python
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.

python
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:

bash
mypy your_module.py

If you try to assign a value of the wrong type, mypy will flag it. Consider this function:

python
def update_email(user: User, new_email: str) -> None: user['email'] = new_email

If 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:

python
class User(TypedDict, total=False): id: int name: str email: str phone: str # optional

With total=False, every key becomes optional. You can also mix required and optional keys by using inheritance:

python
class BaseUser(TypedDict): id: int name: str class FullUser(BaseUser, total=False): email: str phone: str

Here, 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.

FeatureTypedDictDataclassNamedTuple
Runtime typedictcustom classtuple subclass
Access styleuser['name']user.nameuser.name
Runtime validationNoneNone (unless coded)None
JSON serializationDirectNeeds conversionNeeds conversion
Best forJSON-like dataDomain objectsLightweight 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 tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.