API reference


check_type(argname, value, expected_type, memo=None, *, globals=None, locals=None)

Ensure that value matches expected_type.

The types from the typing module do not support isinstance() or issubclass() so a number of type specific checks are required. This function knows which checker to call for which type.

  • argname (str) – name of the argument to check; used for error messages

  • value – value to be checked against expected_type

  • expected_type – a class or generic type instance

  • globals (Optional[Dict[str, Any]]) – dictionary of global variables to use for resolving forward references (defaults to the calling frame’s globals)

  • locals (Optional[Dict[str, Any]]) – dictionary of local variables to use for resolving forward references (defaults to the calling frame’s locals)

Return type



Check that the argument values match the annotated types.

Unless both args and kwargs are provided, the information will be retrieved from the previous stack frame (ie. from the function that called this).

Return type





TypeError – if there is an argument type mismatch

check_return_type(retval, memo=None)

Check that the return value is compatible with the return value annotation in the function.


retval – the value about to be returned from the call

Return type





TypeError – if there is a type mismatch

@typechecked(*, always: bool = 'False') → Callable[[T_CallableOrType], T_CallableOrType]
@typechecked(func: T_CallableOrType, *, always: bool = 'False') → T_CallableOrType

Perform runtime type checking on the arguments that are passed to the wrapped function.

The return value is also checked against the return annotation if any.

If the __debug__ global variable is set to False, no wrapping and therefore no type checking is done, unless always is True.

This can also be used as a class decorator. This will wrap all type annotated methods in the class with this decorator.

  • func – the function or class to enable type checking for

  • alwaysTrue to enable type checks even in optimized mode

class TypeChecker(packages, *, all_threads=True, forward_refs_policy=<ForwardRefPolicy.ERROR: 1>)

A type checker that collects type violations by hooking into sys.setprofile().

  • packages (Union[str, Sequence[str]]) – list of top level modules and packages or modules to include for type checking

  • all_threads (bool) – True to check types in all threads created while the checker is running, False to only check in the current one

  • forward_refs_policy (ForwardRefPolicy) – how to handle unresolvable forward references in annotations

Deprecated since version 2.6: Use install_import_hook() instead. This class will be removed in v3.0.

exception TypeHintWarning

A warning that is emitted when a type hint in string form could not be resolved to an actual type.

exception TypeWarning(memo, event, frame, exception)

A warning that is emitted when a type check fails.

  • event (str) – call or return

  • func (Callable) – the function in which the violation occurred (the called function if event is call, or the function where a value of the wrong type was returned from if event is return)

  • error (str) – the error message contained by the caught TypeError

  • frame – the frame in which the violation occurred

class ForwardRefPolicy(value)

Defines how unresolved forward references are handled.


propagate the NameError from get_type_hints()


replace the annotation with the argument’s class if the qualified name matches, else remove the annotation

WARN = 2

remove the annotation and emit a TypeHintWarning


class TypeguardFinder(packages, original_pathfinder)

Wraps another path finder and instruments the module with @typechecked if should_instrument() returns True.

Should not be used directly, but rather via install_import_hook().

New in version 2.6.


Determine whether the module with the given name should be instrumented.


module_name (str) – full name of the module that is about to be imported (e.g. xyz.abc)

Return type


install_import_hook(packages, *, cls=<class 'typeguard.importhook.TypeguardFinder'>)

Install an import hook that decorates classes and functions with @typechecked.

This only affects modules loaded after this hook has been installed.

Return type



a context manager that uninstalls the hook on exit (or when you call .uninstall())

New in version 2.6.