{"id":590,"library":"typeguard","title":"Typeguard","description":"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.","status":"active","version":"4.5.1","language":"python","source_language":"en","source_url":"https://github.com/agronholm/typeguard","tags":["type checking","runtime","type hints","annotations","validation"],"install":[{"cmd":"pip install typeguard","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"typechecked","correct":"from typeguard import typechecked"},{"symbol":"check_type","correct":"from typeguard import check_type"},{"symbol":"install_import_hook","correct":"from typeguard import install_import_hook"},{"symbol":"suppress_type_checks","correct":"from typeguard import suppress_type_checks"},{"symbol":"typeguard_ignore","correct":"from typeguard import typeguard_ignore"},{"note":"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.","wrong":"check_argument_types() alone for comprehensive checks (use @typechecked or check_type instead)","symbol":"check_argument_types","correct":"from typeguard import check_argument_types"}],"quickstart":{"code":"from typeguard import typechecked\nfrom typing import List\n\n@typechecked\ndef process_data(data: List[int], multiplier: float) -> List[float]:\n    \"\"\"Processes a list of integers, multiplies each by a float, and returns a list of floats.\"\"\"\n    return [item * multiplier for item in data]\n\n@typechecked\nclass MyCalculator:\n    def __init__(self, offset: int):\n        self.offset = offset\n\n    def add(self, a: int, b: int) -> int:\n        return a + b + self.offset\n\n\n# --- Successful usage ---\nprint(f\"Processed data: {process_data([1, 2, 3], 2.5)}\") # Expected: [2.5, 5.0, 7.5]\ncalculator = MyCalculator(offset=10)\nprint(f\"Calculator sum: {calculator.add(5, 7)}\") # Expected: 22\n\n# --- Intentional type errors (will raise TypeError) ---\ntry:\n    process_data([1, '2', 3], 2.5) # data contains a string instead of int\nexcept TypeError as e:\n    print(f\"Caught expected error (list item type): {e}\")\n\ntry:\n    process_data([1, 2, 3], '2.5') # multiplier is a string instead of float\nexcept TypeError as e:\n    print(f\"Caught expected error (argument type): {e}\")\n\ntry:\n    calculator.add(5, 'seven') # b is a string instead of int\nexcept TypeError as e:\n    print(f\"Caught expected error (method argument type): {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 4.5.0 introduced a breaking change where `check_argument_types()` started receiving an unexpected keyword argument 'memo', causing issues in downstream libraries.","severity":"breaking","affected_versions":">=4.5.0"},{"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`).","message":"The `@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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Direct 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.","severity":"deprecated","affected_versions":"All versions"},{"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`.","message":"Typeguard has dropped support for Python 3.8 in recent major versions (e.g., in the 4.x series).","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"Typeguard 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that arguments passed to type-checked functions and their return values strictly conform to their specified type hints to avoid `TypeCheckError`.","message":"Typeguard 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T16:22:52.566Z","next_check":"2026-06-26T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"4.5.1","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.32,"mem_mb":8.4,"disk_size":"18.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":8.4,"disk_size":"18.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.21,"mem_mb":8.4,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":8.4,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":10,"disk_size":"20.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.47,"mem_mb":10,"disk_size":"20.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.36,"mem_mb":10,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.34,"mem_mb":10,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":9.7,"disk_size":"12.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.67,"mem_mb":9.7,"disk_size":"12.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.64,"mem_mb":9.7,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.62,"mem_mb":9.7,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.64,"mem_mb":10.2,"disk_size":"11.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":10.2,"disk_size":"11.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.58,"mem_mb":10.2,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.6,"mem_mb":10.2,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":14.6,"disk_size":"18.2M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":14.6,"disk_size":"18.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2,"import_time_s":0.34,"mem_mb":14.6,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.31,"mem_mb":14.6,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}