NotRequired

NotRequired is a typing construct used with TypedDict in Python to indicate that a particular key in a dictionary type is optional. When a key is annotated with NotRequired, a dictionary conforming to the TypedDict may omit that key entirely, but if the key is present, its value must conform to the specified type.

NotRequired was introduced as part of PEP 655 and is available in Python 3.11 and later. Before its inclusion in the standard library, the functionality could be accessed via the typing_extensions backport for older Python versions. The intent is to provide more precise type checking for dictionaries where some fields are optional.

To use NotRequired, you declare a TypedDict class and annotate optional keys with NotRequired. For example, a Movie TypedDict might declare title as a required field and year as NotRequired[int]. This allows dictionaries like {"title": "Inception"} and {"title": "Inception", "year": 2010} to be valid, while still enforcing the value type when the key is present. Note that NotRequired governs the presence of the key, not whether the value can be None; Optional is used to indicate that a value may be None, while NotRequired concerns key existence.

NotRequired is supported by major type checkers such as Mypy and Pyright, with varying history of support in older toolchains. For projects targeting older Python versions, the backport via typing_extensions remains an option. See also TypedDict, Required, and PEP 655.