reportUnnecessaryCast.md

April 8, 2026 · View on GitHub

Overview

reportUnnecessaryCast is a diagnostic in Pylance and Pyright that warns when a type cast is unnecessary because the type is already known or compatible. This helps keep code clean and avoids redundant or misleading type annotations.

Representative Issues

  • #450: Avoid using type: ignore comments unless absolutely necessary; instead, use more specific error handling methods like casts or asserts to manage type errors.
  • #7990: Use TypeIs for specific type checks and avoid unnecessary checks that could be simplified or removed.

Examples

Error:

from typing import cast

def process(value: int) -> int:
    return cast(int, value)  # Cast is unnecessary; value is already int

Fix — remove the redundant cast:

def process(value: int) -> int:
    return value

Common Fixes & Workarounds

  1. Remove unnecessary casts when the type is already correct or compatible.
  2. Use explicit type annotations or asserts only when needed for clarity or type narrowing.
  3. Prefer more specific error handling or type checking methods over broad type: ignore comments.
  4. Review the Pyright configuration documentation for options to adjust or suppress this diagnostic if needed.

See Also