Skip to content
Back to top
View this page
Edit this page

# TypedDict

Python programs often use dictionaries with string keys to represent objects. `TypedDict` lets you give precise types for dictionaries that represent objects with a fixed schema, such as `{'id': 1, 'items': ['x']}`.

Here is a typical example:

    movie = {'name': 'Blade Runner', 'year': 1982}

Only a fixed set of string keys is expected (`'name'` and `'year'` above), and each key has an independent value type (`str` for `'name'` and `int` for `'year'` above). We’ve previously seen the `dict[K, V]` type, which lets you declare uniform dictionary types, where every value has the same type, and arbitrary keys are supported. This is clearly not a good fit for `movie` above. Instead, you can use a `TypedDict` to give a precise type for objects like `movie`, where the type of each dictionary value depends on the key:

    from typing import TypedDict

    Movie = TypedDict('Movie', {'name': str, 'year': int})

    movie: Movie = {'name': 'Blade Runner', 'year': 1982}

`Movie` is a `TypedDict` type with two items: `'name'` (with type `str`) and `'year'` (with type `int`). Note that we used an explicit type annotation for the `movie` variable. This type annotation is important – without it, mypy will try to infer a regular, uniform `dict` type for `movie`, which is not what we want here.

Note

If you pass a `TypedDict` object as an argument to a function, no type annotation is usually necessary since mypy can infer the desired type based on the declared argument type. Also, if an assignment target has been previously defined, and it has a `TypedDict` type, mypy will treat the assigned value as a `TypedDict`, not `dict`.

Now mypy will recognize these as valid:

    name = movie['name']  # Okay; type of name is str
    year = movie['year']  # Okay; type of year is int

Mypy will detect an invalid key as an error:

    director = movie['director']  # Error: 'director' is not a valid key

Mypy will also reject a runtime-computed expression as a key, as it can’t verify that it’s a valid key. You can only use string literals as `TypedDict` keys.

The `TypedDict` type object can also act as a constructor. It returns a normal `dict` object at runtime – a `TypedDict` does not define a new runtime type:

    toy_story = Movie(name='Toy Story', year=1995)

This is equivalent to just constructing a dictionary directly using `{ ... }` or `dict(key=value, ...)`. The constructor form is sometimes convenient, since it can be used without a type annotation, and it also makes the type of the object explicit.

Like all types, `TypedDict`s can be used as components to build arbitrarily complex types. For example, you can define nested `TypedDict`s and containers with `TypedDict` items. Unlike most other types, mypy uses structural compatibility checking (or structural subtyping) with `TypedDict`s. A `TypedDict` object with extra items can be compatible with (a subtype of) a narrower `TypedDict`, assuming item types are compatible (totality also affects subtyping, as does closing, as discussed below).

A `TypedDict` object is not a subtype of the regular `dict[...]` type (and vice versa), since `dict` allows arbitrary keys to be added and removed, unlike `TypedDict`. However, any `TypedDict` object is a subtype of (that is, compatible with) `Mapping[str, object]`, since `Mapping` only provides read-only access to the dictionary items:

    def print_typed_dict(obj: Mapping[str, object]) -> None:
        for key, value in obj.items():
            print(f'{key}: {value}')

    print_typed_dict(Movie(name='Toy Story', year=1995))  # OK

Note

Unless you are on Python 3.8 or newer (where `TypedDict` is available in standard library `typing` module) you need to install `typing_extensions` using pip to use `TypedDict`:

    python3 -m pip install --upgrade typing-extensions

## Totality

By default mypy ensures that a `TypedDict` object has all the specified keys. This will be flagged as an error:

    # Error: 'year' missing
    toy_story: Movie = {'name': 'Toy Story'}

Sometimes you want to allow keys to be left out when creating a `TypedDict` object. You can provide the `total=False` argument to `TypedDict(...)` to achieve this:

    GuiOptions = TypedDict(
        'GuiOptions', {'language': str, 'color': str}, total=False)
    options: GuiOptions = {}  # Okay
    options['language'] = 'en'

You may need to use `get()` to access items of a partial (non-total) `TypedDict`, since indexing using `[]` could fail at runtime. However, mypy still lets use `[]` with a partial `TypedDict` – you just need to be careful with it, as it could result in a `KeyError`. Requiring `get()` everywhere would be too cumbersome. (Note that you are free to use `get()` with total `TypedDict`s as well.)

Keys that aren’t required are shown with a `?` in error messages:

    # Revealed type is "TypedDict('GuiOptions', {'language'?: builtins.str,
    #                                            'color'?: builtins.str})"
    reveal_type(options)

Totality also affects structural compatibility. You can’t use a partial `TypedDict` when a total one is expected. Also, a total `TypedDict` is not valid when a partial one is expected.

## Supported operations

`TypedDict` objects support a subset of dictionary operations and methods. You must use string literals as keys when calling most of the methods, as otherwise mypy won’t be able to check that the key is valid. List of supported operations:

- Anything included in `Mapping`:

  - `d[key]`

  - `key in d`

  - `len(d)`

  - `for key in d` (iteration)

  - `d.get(key[, default])`

  - `d.keys()`

  - `d.values()`

  - `d.items()`

- `d.copy()`

- `d.setdefault(key, default)`

- `d1.update(d2)`

- `d.pop(key[, default])` (partial `TypedDict`s only)

- `del d[key]` (partial `TypedDict`s only)

Note

`clear()` and `popitem()` are not supported since they are unsafe – they could delete required `TypedDict` items that are not visible to mypy because of structural subtyping.

## Class-based syntax

An alternative, class-based syntax to define a `TypedDict` is supported in Python 3.6 and later:

    from typing import TypedDict  # "from typing_extensions" in Python 3.7 and earlier

    class Movie(TypedDict):
        name: str
        year: int

The above definition is equivalent to the original `Movie` definition. It doesn’t actually define a real class. This syntax also supports a form of inheritance – subclasses can define additional items. However, this is primarily a notational shortcut. Since mypy uses structural compatibility with `TypedDict`s, inheritance is not required for compatibility. Here is an example of inheritance:

    class Movie(TypedDict):
        name: str
        year: int

    class BookBasedMovie(Movie):
        based_on: str

Now `BookBasedMovie` has keys `name`, `year` and `based_on`.

## Mixing required and non-required items

In addition to allowing reuse across `TypedDict` types, inheritance also allows you to mix required and non-required (using `total=False`) items in a single `TypedDict`. Example:

    class MovieBase(TypedDict):
        name: str
        year: int

    class Movie(MovieBase, total=False):
        based_on: str

Now `Movie` has required keys `name` and `year`, while `based_on` can be left out when constructing an object. A `TypedDict` with a mix of required and non-required keys, such as `Movie` above, will only be compatible with another `TypedDict` if all required keys in the other `TypedDict` are required keys in the first `TypedDict`, and all non-required keys of the other `TypedDict` are also non-required keys in the first `TypedDict`.

## Read-only items

You can use `typing.ReadOnly`, introduced in Python 3.13, or `typing_extensions.ReadOnly` to mark TypedDict items as read-only (PEP 705):

    from typing import TypedDict

    # Or "from typing ..." on Python 3.13+
    from typing_extensions import ReadOnly

    class Movie(TypedDict):
        name: ReadOnly[str]
        num_watched: int

    m: Movie = {"name": "Jaws", "num_watched": 1}
    m["name"] = "The Godfather"  # Error: "name" is read-only
    m["num_watched"] += 1  # OK

A TypedDict with a mutable item can be assigned to a TypedDict with a corresponding read-only item, and the type of the item can vary covariantly:

    class Entry(TypedDict):
        name: ReadOnly[str | None]
        year: ReadOnly[int]

    class Movie(TypedDict):
        name: str
        year: int

    def process_entry(i: Entry) -> None: ...

    m: Movie = {"name": "Jaws", "year": 1975}
    process_entry(m)  # OK

You can override a read-only item with a compatible subtype, make a read-only item mutable, and inherit from multiple parents with compatible definitions:

    from collections.abc import Collection, Sequence

    class Competition(TypedDict):
        hosts: ReadOnly[Collection[str]]
        entries: ReadOnly[Sequence[Entry]]

    class MovieShow(TypedDict):
        entries: list[Movie]

    class Oscars(Competition, MovieShow):
        hosts: set[str]

Defining `hosts` as a mutable `set[str]` item works as this is compatible with the read-only `Collection[str]` definition in `Competition`. `entries` will be of type `list[Movie]`, taken from the `MovieShow` type, as it is the only non-readonly definition, and is compatible with the definition in `Competition`.

If an item is only defined in supertypes, and is always read-only, mypy takes the definition from the first parent in the inheritance order, and raises an error if any other parent definition is incompatible:

    class NameIds(TypedDict):
        ids: ReadOnly[Collection[str]]

    class OrderedIds(TypedDict):
        ids: ReadOnly[Sequence[int | str]]

    class OrderedNameIds(NameIds, OrderedIds):
        pass  # Error! Parent definitions incompatible

In this example, the definition of `ids` will be taken from `NameIds`, which would not be compatible with the definition in `OrderedIds`; reordering the parents would not solve the problem. Instead, you will need to make a compatible definition explicitly:

    class OrderedNameIds(NameIds, OrderedIds):
        ids: ReadOnly[Sequence[str]]

## Closing

You can use the `closed` keyword, introduced to `TypedDict` in Python 3.15 (and available via `typing_extensions.TypedDict` in older versions) to prevent structural subtypes from adding extra keys to a type (PEP 728):

    HasName = TypedDict("HasName", {"name": str})
    HasOnlyName = TypedDict("HasOnlyName", {"name": str}, closed=True)
    Movie = TypedDict("Movie", {"name": str, "year": int})

    movie: Movie = {"name": "Nimona", "year": 2023}
    has_name: HasName = movie  # OK: type is open
    has_only_name: HasOnlyName = movie  # Error: type is closed

This allows the typechecker to determine that certain operations are safe, when they otherwise wouldn’t be due to the potential presence of unknown keys.

The `closed` keyword can also be used in class-based syntax:

    class HasOnlyName(TypedDict, closed=True):
        name: str

## Unions of TypedDicts

Since TypedDicts are really just regular dicts at runtime, it is not possible to use `isinstance` checks to distinguish between different variants of a Union of TypedDict in the same way you can with regular objects.

Instead, you can use the tagged union pattern. The referenced section of the docs has a full description with an example, but in short, you will need to give each TypedDict the same key where each value has a unique Literal type. Then, check that key to distinguish between your TypedDicts.

Alternatively, you can implement tagged unions with single-key wrapper dictionaries:

    class Book(TypedDict):
        name: str
        length: int
        ...

    class DVD(TypedDict):
        name: str
        length: int
        ...

    TaggedBook = TypedDict('TaggedBook', {'book': Book}, closed=True)
    TaggedDVD = TypedDict('TaggedDVD', {'dvd': DVD}, closed=True)
    type Inventory = TaggedBook | TaggedDVD

    def print_length(inventory: Inventory) -> None:
        if "book" in inventory:
            print(inventory["book"]["length"], 'pages')
        else:
            print(inventory["dvd"]["length"], 'minutes')

Here, the `closed` keyword is necessary to allow the `if` guard to safely narrow the types; without it, there could be a structural subtype of `TaggedDVD` that contains a `book` field of arbitrary type.

Note

Applying `@final` to a TypedDict is a legacy way of marking it as closed for the purposes of type narrowing. It was never fully implemented and is now superseded; it may be removed in future.

## Inline TypedDict types

Note

This is an experimental (non-standard) feature. Use `--enable-incomplete-feature=InlineTypedDict` to enable.

Sometimes you may want to define a complex nested JSON schema, or annotate a one-off function that returns a TypedDict. In such cases it may be convenient to use inline TypedDict syntax. For example:

    def test_values() -> {"width": int, "description": str}:
        return {"width": 42, "description": "test"}

    class Response(TypedDict):
        status: int
        msg: str
        # Using inline syntax here avoids defining two additional TypedDicts.
        content: {"items": list[{"key": str, "value": str}]}

Inline TypedDicts can also by used as targets of type aliases, but due to ambiguity with a regular variables it is only allowed for (newer) explicit type alias forms:

    from typing import TypeAlias

    X = {"a": int, "b": int}  # creates a variable with type dict[str, type[int]]
    Y: TypeAlias = {"a": int, "b": int}  # creates a type alias
    type Z = {"a": int, "b": int}  # same as above (Python 3.12+ only)

Also, due to incompatibility with runtime type-checking it is strongly recommended to not use inline syntax in union types.