---
id: flake8-typing-imports
version: "1.17.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# flake8-typing-imports — flake8 plugin which checks that typing imports are properly guarded

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

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

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

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

## Tags

flake8 typing imports guard, type checking import validation, python typing compatibility checker, flake8 plugin typing, guard typing imports, typing module version checks, TYPE_CHECKING guard enforcement, type-checking, flake8-plugin, linting

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