flake8-typing-imports

What it is and what it does

This is a flake8 plugin that enforces safe typing imports by checking that typing module usage matches your minimum supported Python version. The typing module has seen significant API changes across Python versions, and this plugin catches cases where you import or use typing constructs that don't exist in all your target versions—flagging them with codes like TYP001 (unguarded import), TYP002 (@overload issues), TYP003 (unquoted Union/Pattern), TYP004–TYP005 (NamedTuple limitations), and TYP006 (unquoted typing attributes).

You configure it with a minimum Python version (defaulting to 3.5.0, or read from setup.cfg's python_requires), and it runs as part of your normal flake8 checks. It helps you avoid runtime errors by ensuring that imports are either guarded behind TYPE_CHECKING blocks or version checks, or that you quote type hints that aren't available in all supported versions.

Use it for:

• Enforce TYPE_CHECKING guards in a codebase that supports multiple Python versions to avoid runtime import errors.
• Catch typing API usage that's broken or unavailable in your minimum supported Python version during CI/CD.
• Validate that NamedTuple definitions don't use unsupported features like methods or defaults in older Python versions.
• Automatically check that Union[Match, ...] and Union[Pattern, ...] are quoted when targeting Python <3.5.2.
• Integrate typing safety checks into pre-commit hooks alongside other flake8 linting rules.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A flake8 plugin that detects unguarded typing imports and version-specific typing API issues across Python versions, flagging imports that need TYPE_CHECKING guards or version checks.

Yes. This is a lightweight, actively maintained plugin that solves a real problem—typing module instability across Python versions—with zero security issues and minimal install friction. If you support multiple Python versions and use type hints, it catches mistakes that are otherwise easy to miss and can cause runtime failures in older environments.

Install

flake8-typing-imports on PyPI

pip install flake8-typing-imports

uv add flake8-typing-imports

poetry add flake8-typing-imports

Installing flake8-typing-imports

Before you install

Low friction: pure Python wheel with only flake8 as a runtime dependency. Actively maintained with a recent release (2025-10-09) and no known vulnerabilities.

License in practice

MIT license is permissive; you can use, modify, and distribute this plugin freely with minimal restrictions.

Quickstart

pip install flake8-typing-imports

# Then run flake8 normally; the plugin integrates automatically
flake8 your_code.py

# Configure minimum Python version in .flake8 or setup.cfg:
# [flake8]
# min_python_version = 3.6.0

Requires Python 3.9 or later; flake8 must be installed and available in your environment.

Verify before relying

• Whether the plugin correctly handles all edge cases in typing module changes across Python versions 3.5.0–3.7.2 as claimed.
• Performance impact when running on large codebases with many typing imports.

Package facts

Evidence: flake8_typing_imports-1.17.0-py2.py3-none-any.whl

Tags

More Quality Assurance packages