flake8-type-checking

3.2.0 verified Fri May 01 auth: no python

A flake8 plugin for managing type-checking imports and forward references. Current version 3.2.0, requires Python >=3.10. Released irregularly with multiple minor versions per year.

pip install flake8-type-checking

Common errors

error tc001: import move to type-checking block ↓

cause Import that is only used in type annotations is not inside a TYPE_CHECKING block.

fix

Move the import inside an if TYPE_CHECKING: block.

error tc002: import move to type-checking block (ignored by default) ↓

cause Similar to TC001, but for symbols that are used both as type hints and at runtime. The plugin suggests splitting imports.

fix

Use if TYPE_CHECKING: for the type-only part and a separate runtime import if needed, or add a # noqa: TC002 comment.

error tc100: multiple type annotations to be moved to TYPE_CHECKING block ↓

cause Several imports are used only in type annotations but not wrapped.

fix

Move all such imports into an if TYPE_CHECKING: block.

error tc200: forward reference annotation should use string literal ↓

cause A type annotation references a name that hasn't been imported at runtime, but was not quoted.

fix

Quote the annotation, e.g., def foo() -> 'Bar':

Warnings

breaking v3.0.0 broke detection of re-exported typing symbols like `cast` and `Annotated` from non-typing modules. You must configure `type-checking-typing-modules` if you re-export them. ↓

fix Add `type-checking-typing-modules = mymodule.typing` to your flake8 config, where `mymodule.typing` is the module that re-exports.

gotcha The plugin treats `TYPE_CHECKING` blocks specially; ordinary conditional imports (e.g., `if False:`) are not recognized. Only `from typing import TYPE_CHECKING` (or `typing.TYPE_CHECKING`) triggers the plugin's logic. ↓

fix Always import TYPE_CHECKING from typing, not from other modules.

deprecated Python 3.8 support dropped in v3.0.0; Python 3.10+ required. ↓

fix Upgrade to Python 3.10 or later.

gotcha TC010 (invalid use of string literals with `|`) was added in v2.9.0. It flags union types as strings even when they are syntactically valid in Python 3.10+. This may cause false positives for type annotations that are not evaluated at runtime. ↓

fix Use `from __future__ import annotations` or convert string annotations to actual type hints, or disable TC010 with `extend-ignore = TC010`.

Imports

flake8_type_checking
wrong
```
import flake8-type-checking
```
correct
```
from flake8_type_checking import ...
```
Hyphens not allowed in Python imports; use underscores

Quickstart

Basic usage: install and configure flake8, then add ignore or error codes as needed. The plugin automatically detects TYPE_CHECKING blocks.

# file: setup.cfg or .flake8
[flake8]
extend-ignore = TC001,TC002  # adjust as needed

# file: example.py
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from foo import Bar  # acceptable if only used in type hints

def greet() -> None:
    # Use Bar here? Actually, only for type checking
    pass