Registry / testing / typeguard

typeguard

JSON →
library4.6.0pypypi✓ verified 29d ago

Typeguard is a Python library that provides run-time type checking for functions and methods defined with PEP 484 type annotations, as well as for arbitrary objects. It acts as an additional layer of type safety alongside static type checkers like MyPy, catching type violations that can only be detected at run time. Currently at version 4.5.1, the library is actively maintained with regular updates.

pip install typeguard
INSTALL
IMPORT
SIG · TYPEGUARD
T
typeguard
testingpythonv4.6.0
Install
1.8s avg
Import
452ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v4.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.474s · 18.4MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.430s · 19MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

typechecked
✓ from typeguard import typechecked
check_type
✓ from typeguard import check_type
install_import_hook
✓ from typeguard import install_import_hook
suppress_type_checks
✓ from typeguard import suppress_type_checks
typeguard_ignore
✓ from typeguard import typeguard_ignore
check_argument_types
✓ from typeguard import check_argument_types
✗ check_argument_types() alone for comprehensive checks (use @typechecked or check_type instead)
While still available, `check_argument_types()` has limitations (e.g., cannot check return values, doesn't reliably work with dynamic type hints, and had a breaking change in 4.5.0). The `@typechecked` decorator or `check_type` function are generally preferred for more robust and comprehensive runtime type enforcement.

This quickstart demonstrates using the `@typechecked` decorator on both functions and methods. It shows successful type checking and how `typeguard` raises a `TypeError` when type annotations are violated at runtime.

from typeguard import typechecked from typing import List @typechecked def process_data(data: List[int], multiplier: float) -> List[float]: """Processes a list of integers, multiplies each by a float, and returns a list of floats.""" return [item * multiplier for item in data] @typechecked class MyCalculator: def __init__(self, offset: int): self.offset = offset def add(self, a: int, b: int) -> int: return a + b + self.offset # --- Successful usage --- print(f"Processed data: {process_data([1, 2, 3], 2.5)}") # Expected: [2.5, 5.0, 7.5] calculator = MyCalculator(offset=10) print(f"Calculator sum: {calculator.add(5, 7)}") # Expected: 22 # --- Intentional type errors (will raise TypeError) --- try: process_data([1, '2', 3], 2.5) # data contains a string instead of int except TypeError as e: print(f"Caught expected error (list item type): {e}") try: process_data([1, 2, 3], '2.5') # multiplier is a string instead of float except TypeError as e: print(f"Caught expected error (argument type): {e}") try: calculator.add(5, 'seven') # b is a string instead of int except TypeError as e: print(f"Caught expected error (method argument type): {e}")
Debug
Known issues
breakingVersion 4.5.0 introduced a breaking change where `check_argument_types()` started receiving an unexpected keyword argument 'memo', causing issues in downstream libraries.
fix
If encountering `TypeError: check_argument_types() got an unexpected keyword argument 'memo'`, consider downgrading to `typeguard==4.4.1` or refactoring code to use `@typechecked` or `check_type` which are less susceptible to this specific issue.
affects: >=4.5.0
gotchaThe `@typechecked` decorator becomes a no-op when Python is run in optimized mode (`python -O` or by setting the `PYTHONOPTIMIZE` environment variable). This can lead to silent disabling of runtime type checks in production environments.
fix
Be aware of this behavior and explicitly configure type checking for production if it's critical. If you need runtime checks in optimized mode, you would need to use `check_type()` explicitly or ensure the import hook is installed in a way that bypasses this optimization behavior (which is not the default for `@typechecked`).
affects: All versions
deprecatedDirect use of `check_argument_types()` and `check_return_type()` has limitations, such as not working reliably with dynamically defined type hints (e.g., in nested functions) and being less comprehensive than the `@typechecked` decorator.
fix
Prefer using the `@typechecked` decorator for functions and methods, or the `check_type()` function for individual value checks, as these provide more robust and reliable runtime type enforcement.
affects: All versions
breakingTypeguard has dropped support for Python 3.8 in recent major versions (e.g., in the 4.x series).
fix
Ensure your project runs on Python 3.9 or newer to use the latest versions of Typeguard. The `requires_python` metadata on PyPI reflects this, currently `>=3.9`.
affects: >=4.0.0
gotchaTypeguard enforces runtime type checks and will raise a `typeguard.TypeCheckError` when an argument or return value does not match its annotated type at runtime. This is Typeguard's core functionality.
fix
Ensure that all values passed to functions or returned from them strictly adhere to their type annotations to avoid `TypeCheckError`. Use static type checkers (e.g., MyPy) during development to catch such issues preemptively, and implement careful input validation if external data is involved.
affects: All versions
gotchaTypeguard raises `typeguard.TypeCheckError` when a function argument or return value does not match its annotated type. This is its core functionality and will prevent execution with incorrect types.
fix
Ensure that arguments passed to type-checked functions and their return values strictly conform to their specified type hints to avoid `TypeCheckError`.
affects: All versions
Upgrade
Version history
4.6.0latest on PyPI · released Jul 26, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
1
Resources
typeguard — pip install typeguard · libregistry