flake8-typing-imports

1.17.0 verified Mon Apr 27 auth: no python

Flake8 plugin enforcing that typing imports are guarded by `if TYPE_CHECKING` to avoid runtime import overhead and circular imports. Current version 1.17.0, requires Python >=3.9. Maintained by asottile, stable release cadence.

pip install flake8-typing-imports

Common errors

error TYP001: Import `typing` is not guarded by `TYPE_CHECKING` ↓

cause A `typing` import (e.g., `from typing import List`) is placed at module level without an `if TYPE_CHECKING:` guard.

fix

Put the import inside an if TYPE_CHECKING: block: if TYPE_CHECKING: from typing import List

error TYP002: Import `collections.abc` is not guarded by `TYPE_CHECKING` ↓

cause A `collections.abc` import is not guarded.

fix

Guard the import with if TYPE_CHECKING:.

Warnings

breaking In version 1.6.0, the default codes changed from TYP001, TYP002 etc. to a new scheme. Old codes may no longer be valid. ↓

fix Update your flake8 configuration to use the new codes (TYP001, TYP002, etc. are still supported but deprecated). See changelog.

gotcha The plugin checks for `TYPE_CHECKING` guard on imports of `typing` and `collections.abc`, but it does not flag other modules like `types`. You must manually guard them. ↓

fix Manually guard imports from modules like `types` if needed.

gotcha The plugin only detects `from foo import bar` guarded imports; bare imports like `import foo` inside `if TYPE_CHECKING` are not flagged if they are not from typing-related modules. ↓

fix Ensure all typing imports use `from ... import ...` syntax if guarding.

deprecated Support for Python 3.7 ended in version 1.15.0; Python 3.8 ended in 1.16.0. Running on older Python versions will not work. ↓

fix Upgrade to Python >=3.9.

Imports

flake8_typing_imports
flaek8 loads plugins automatically; no manual import needed.

Quickstart

Create a file with a guarded import and run flake8 with the TYP selector to check typing imports.

cat > example.py << 'EOF'
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from collections import abc

foo: abc.Iterable
EOF
pip install flake8 flake8-typing-imports
flake8 example.py --select=TYP