Beartype

0.22.9 verified Tue May 12 auth: no python install: verified quickstart: verified

Beartype is an open-source, pure-Python, PEP-compliant, near-real-time runtime-static type-checker. It emphasizes efficiency, portability, and readability, ensuring O(1) non-amortized worst-case runtime complexity with negligible constant factors. The library has no runtime dependencies and is actively maintained with frequent patch releases addressing compatibility and bug fixes, as evidenced by its rapid `0.22.x` release cycle.

pip install beartype

Common errors

error BeartypeCallHintParamViolation: Function calculate_statistics() parameter data=[1, 'a', 3] violates type hint list[float], as list index 0 item int 1 not instance of float. ↓

cause This error occurs when a function decorated with `@beartype` receives a parameter whose runtime type does not match the annotated type hint, indicating a type-checking violation at call time.

fix

Ensure that the arguments passed to the @beartype-decorated function conform to their specified type hints. For the example, data should contain only float instances.

error BeartypeDecorHintForwardRefException: Forward reference "__main__. List[MyCls]" syntactically invalid as module attribute name. ↓

cause This exception is raised at decoration time when a forward reference (a type hint specified as a string) is syntactically malformed or incorrectly references a type that cannot be resolved by `beartype`.

fix

Correct the stringified forward reference to accurately reflect the type, ensuring it's a valid identifier or path to the target class, often by only stringifying the yet-to-be-defined class (e.g., List["MyCls"]) or using from __future__ import annotations if applicable.

error ImportError: cannot import name 'List' from 'typing' ↓

cause This error typically occurs in Python 3.9+ when trying to import generic types like `List`, `Dict`, or `Tuple` from the `typing` module, as PEP 585 (Python 3.9+) and PEP 604 (Python 3.10+) made built-in generics (e.g., `list`, `dict`) the standard for type hints. `beartype` often warns about this impending breakage in older Python versions.

fix

Replace imports like from typing import List with the direct use of built-in generic types (e.g., list[str]) or use from __future__ import annotations (which effectively enables built-in generics in older Python versions).

error ImportError: cannot import name 'ByteString' from 'collections.abc' ↓

cause This error arises in Python 3.14 and newer versions because `typing.ByteString` (and its corresponding `collections.abc.ByteString`) has been deprecated and subsequently removed.

fix

Replace ByteString with the built-in bytes type, as bytes is the appropriate type hint for byte strings.

Warnings

gotcha Type-checking might be inadvertently disabled when `PYTHONOPTIMIZE=1` or the `-O` flag is used with the Python interpreter in versions prior to `0.22.5`. ↓

fix Upgrade to `beartype` 0.22.5 or higher. Alternatively, avoid running Python with `PYTHONOPTIMIZE=1` or the `-O` flag if runtime type-checking is critical for these older versions.

breaking Version `0.22.3` introduced a `pyproject.toml` `requires-python` syntax that caused installation failures with `Poetry` and `pipenv` due to their non-standard parsing behavior. ↓

fix Upgrade to `beartype` 0.22.4 or higher, which addressed these compatibility issues.

gotcha Synchronous generator functions decorated with `@beartype` could lose their `inspect.isgeneratorfunction()` property, causing issues with frameworks like Gradio. This was an issue in `0.22.6` and subsequent patches. ↓

fix Upgrade to `beartype` 0.22.8 or higher, which restored `inspect.isgeneratorfunction()`-ness for decorated synchronous generator functions.

gotcha Beartype has known incompatibilities with `Pydantic` due to `Pydantic`'s non-standard handling of `if TYPE_CHECKING:` blocks and forward references, which can break runtime type-checking. Beartype internally 'blacklists' `Pydantic` to prevent crashes. ↓

fix Be aware of potential issues when combining `beartype` with `Pydantic` models. While `beartype` attempts to mitigate conflicts, complex interactions might still arise. Consider using `beartype.door.is_bearable()` or `die_if_unbearable()` for manual checks on Pydantic objects if direct decoration causes problems.

gotcha While `beartype` offers O(1) worst-case type-checking performance, users might perceive a minor overhead when compared to entirely untyped Python code. This is primarily due to the inherent cost of Python's function call stack frames and decorator mechanics, not `beartype`'s specific implementation. ↓

fix Understand that `beartype`'s efficiency refers to the type-checking logic itself, which is highly optimized. The minimal overhead observed is generally a baseline of Python's execution model when decorators are applied, rather than a performance flaw in `beartype`.

gotcha Beartype raises `BeartypeCallHintParamViolation` when arguments passed to a decorated function do not conform to their declared type hints. This is `beartype`'s intended behavior for enforcing runtime type validation, catching type mismatches such as passing bytes where str is expected. ↓

fix Ensure all function arguments strictly adhere to their specified type hints. Review the traceback to identify the specific argument causing the violation and correct the type of the passed value.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.29s 26.8M

3.10 slim (glibc) - - 0.20s 27M

3.11 alpine (musl) - - 0.38s 29.0M

3.11 slim (glibc) - - 0.30s 30M

3.12 alpine (musl) - - 0.32s 20.8M

3.12 slim (glibc) - - 0.32s 21M

3.13 alpine (musl) - - 0.31s 20.3M

3.13 slim (glibc) - - 0.31s 21M

3.9 alpine (musl) - - 0.26s 26.2M

3.9 slim (glibc) - - 0.23s 27M

Imports

beartype
```
from beartype import beartype
```
This is the primary decorator for runtime type-checking of individual functions and methods.
beartype_this_package
```
from beartype.claw import beartype_this_package
```
Used to implicitly apply runtime type-checking across all annotated classes, callables, and variable assignments within an entire Python package. Typically called at the top of a package's `__init__.py`.
Is
```
from beartype.vale import Is
from typing import Annotated
```
Used in conjunction with `typing.Annotated` (Python >= 3.9) to define custom runtime validators for more complex type-checking scenarios.

Quickstart verified last tested: 2026-04-23

This quickstart demonstrates the core usage of the `@beartype` decorator. It shows a function `quote_wiggum` annotated with standard type hints. When called with valid parameters (a list of strings), it executes normally. When called with invalid parameters (a list of bytes), `beartype` intercepts the call and raises a `BeartypeCallHintPepParamException`, providing a clear error message about the type violation.

from beartype import beartype

@beartype
def quote_wiggum(lines: list[str]) -> None:
    print('“{}”\n\t— Police Chief Wiggum'.format("\n ".join(lines)))

# Valid call
quote_wiggum(["Okay, folks. Show's over!", "Nothing to see here."])

# Invalid call (will raise BeartypeCallHintPepParamException)
try:
    quote_wiggum([b"Oh, my God! A horrible plane crash!"])
except Exception as e:
    print(f"Caught expected error: {e.__class__.__name__}: {e}")