flake8-type-checking

What it is and what it does

This flake8 plugin analyzes your code to detect imports used only for type hints and suggests moving them into TYPE_CHECKING blocks. By guarding type-only imports behind TYPE_CHECKING, you eliminate their runtime overhead (important for large libraries like pandas), reduce circular import issues, and organize imports more cleanly. The plugin works by classifying imports as application, third-party, or built-in, then checking whether they're actually used at runtime or only in annotations.

It offers two strategies for handling forward references: TC100-range codes use postponed evaluation (from __future__ import annotations), while TC200-range codes use string literals. You configure which strategy suits your codebase and Python version target. The plugin includes special handling for frameworks like Pydantic and FastAPI, where class annotations are evaluated at runtime, and can be tuned with strict mode, exemptions, and custom typing module paths.

Use it for:

• Reduce import overhead in libraries that use heavy dependencies only for type hints (e.g., pandas, numpy).
• Eliminate circular import errors by moving type-only imports into TYPE_CHECKING blocks.
• Enforce consistent forward-reference style across a codebase (either future annotations or string literals).
• Validate that Pydantic or FastAPI models don't incorrectly guard runtime-needed imports.
• Organize and lint type-checking imports as part of your standard flake8 checks.

Worth the install?

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

A flake8 plugin that identifies which imports should be moved into or out of TYPE_CHECKING blocks to reduce runtime overhead, circular dependencies, and improve code organization.

Yes. This is a focused, low-friction plugin that solves a real problem—unnecessary runtime import overhead and circular dependencies—with active maintenance, no security issues, and permissive licensing. Install it if you want automated guidance on moving type-only imports into TYPE_CHECKING blocks.

Install

flake8-type-checking on PyPI

pip install flake8-type-checking

uv add flake8-type-checking

poetry add flake8-type-checking

Installing flake8-type-checking

Before you install

Low friction install with just two runtime dependencies (flake8 and classify-imports). The package is actively maintained with a recent release and supports current Python versions (3.10–3.14).

License in practice

BSD-3-Clause is a permissive license with no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install flake8-type-checking

# Add to .flake8 config:
# [flake8]
# extend-select = TC, TC2

# Then run flake8 as usual; the plugin will flag imports to move

Requires flake8 to be installed and Python 3.10 or later.

Verify before relying

• Whether the plugin's inference works correctly with all pydantic, fastapi, cattrs, and injector patterns in real codebases.
• Performance impact when running on large projects with many type-checking blocks.

Package facts

Evidence: flake8_type_checking-3.2.0-py3-none-any.whl

Keywords: flake8, plugin, linting, type hint, typing, imports

Tags

More Quality Assurance packages