---
id: flake8-type-checking
version: "3.2.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# flake8-type-checking — A flake8 plugin for managing type-checking imports & forward references

License: permissive · Maintenance: active · Downloads: 109.1K/mo

## 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 above — 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

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

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 109.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

flake8 type checking imports, move imports type checking block, reduce import overhead python, circular dependency imports, type hint import linting, forward reference management, runtime import optimization, flake8-plugin, type-checking, import-optimization

[View on SkillFed](https://skillfed.io/packages/flake8-type-checking) · [View on PyPI](https://pypi.org/project/flake8-type-checking/)