{"id":14980,"library":"torchtyping","title":"torchtyping","description":"torchtyping provides runtime type annotations for PyTorch Tensors, allowing developers to specify and dynamically check the shape, dtype, names, and layout of tensors. It aims to improve code clarity and reduce bugs by enforcing consistent tensor properties. The library is currently at version 0.1.5.","status":"maintenance","version":"0.1.5","language":"en","source_language":"en","source_url":"https://github.com/patrick-kidger/torchtyping","tags":["pytorch","type-checking","type-annotations","tensors","deep-learning","runtime-checking","machine-learning"],"install":[{"cmd":"pip install torchtyping","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core PyTorch dependency for tensor operations.","package":"torch","optional":false},{"reason":"Optional dependency for enabling runtime type checking.","package":"typeguard","optional":true},{"reason":"Required for Python versions prior to 3.9 for full typing support.","package":"typing_extensions","optional":true}],"imports":[{"symbol":"TensorType","correct":"from torchtyping import TensorType"},{"symbol":"patch_typeguard","correct":"from torchtyping import patch_typeguard"}],"quickstart":{"code":"import torch\nfrom torch import rand\nfrom torchtyping import TensorType, patch_typeguard\nfrom typeguard import typechecked\n\n# Call patch_typeguard() once at a global level to enable runtime checking\npatch_typeguard()\n\n@typechecked\ndef add_tensors(x: TensorType['batch'], y: TensorType['batch']) -> TensorType['batch']:\n    return x + y\n\n# This will work as shapes match\nresult_ok = add_tensors(rand(3), rand(3))\nprint(f\"Operation successful: {result_ok.shape}\")\n\n# This would raise a TypeError due to inconsistent 'batch' dimension\ntry:\n    add_tensors(rand(3), rand(1))\nexcept TypeError as e:\n    print(f\"Caught expected error: {e}\")","lang":"python","description":"This quickstart demonstrates how to define a function with `TensorType` annotations for tensor shapes. When `typeguard` is installed and `patch_typeguard()` is called, these annotations are checked at runtime. The example shows both a successful operation and an expected runtime `TypeError` when tensor shapes are inconsistent."},"warnings":[{"fix":"For new projects, use `pip install jaxtyping` and refer to its documentation. For existing projects, consider a migration plan.","message":"The author strongly recommends migrating to 'jaxtyping' instead of 'torchtyping' for new projects. 'jaxtyping' supports PyTorch, is compatible with static type checkers, and is considered the more polished and easier-to-use successor. [2, 12]","severity":"breaking","affected_versions":"<0.1.5"},{"fix":"Ensure `typeguard` is installed with `pip install 'typeguard>=2.11.1,<3'` if you intend to use runtime checks with `torchtyping`.","message":"If using 'typeguard' for runtime checking, a specific version constraint (`typeguard>=2.11.1,<3`) must be followed. Newer versions of 'typeguard' (3.0.0 and above) are not compatible with 'torchtyping'. [2, 5]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware that static type checkers will not validate `torchtyping` annotations. For static type checking compatibility, consider using 'jaxtyping'.","message":"TensorType annotations are not compatible with static type checkers (e.g., MyPy, Pyright). This means static analysis tools will not detect incorrect usage of `TensorType` annotations, limiting their utility for compile-time error detection. [11, 12]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid using `TensorType` annotations on functions or modules intended for TorchScript compilation. Separate code paths or remove annotations if TorchScript is required.","message":"Functions and modules annotated with `TensorType` are not compatible with TorchScript compilation, resulting in 'Unknown type constructor TensorType' errors. [15]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure that all tensors passed to the annotated function have consistent sizes for dimensions sharing the same name (e.g., 'batch'). Adjust input tensor shapes or function logic.","cause":"This error occurs at runtime when `patch_typeguard()` is enabled and a `TensorType` annotated function receives tensors with inconsistent dimensions for a named axis. [2]","error":"TypeError: Dimension 'batch' of inconsistent size. Got both X and Y."},{"fix":"Remove `TensorType` annotations from functions that need to be compiled with TorchScript. Consider using regular `torch.Tensor` annotations or a different approach for runtime checks in TorchScripted code.","cause":"This error arises when attempting to use TorchScript (e.g., `@torch.jit.script`) on functions that have `TensorType` annotations. `TorchScript` does not understand `TensorType` as a valid type constructor. [15]","error":"Unknown type constructor TensorType"},{"fix":"This is expected behavior for `torchtyping`. If static type checking for tensor shapes is desired, migrate to the `jaxtyping` library.","cause":"Unlike its successor `jaxtyping`, `torchtyping` is not designed to be compatible with static type checkers. It only provides runtime checks when `typeguard` is enabled. [11, 12]","error":"Static type checker (e.g., MyPy, Pyright) does not flag errors for incorrect tensor shapes when using `TensorType`."}],"ecosystem":"pypi"}