---
id: flake8-annotations-complexity
version: "0.2.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# flake8-annotations-complexity — A flake8 extension that checks for type annotations complexity

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

## What it is and what it does

flake8-annotations-complexity is a flake8 extension that measures and enforces limits on type annotation complexity. It defines complexity as the maximum nesting level of type brackets—for example, `List[int]` has complexity 2, while `Tuple[List[Optional[str]], int]` has complexity 4. The plugin checks annotations on function arguments (positional, keyword-only, *args, **kwargs), return types (including async functions), and annotated variable assignments.

The plugin provides two checks: TAE002 flags annotations exceeding a nesting-depth threshold (default 3), and TAE003 flags annotations with too many elements (default 7). Both thresholds are configurable via flake8 command-line options. It runs on Python 3.10 through 3.14 and integrates directly into your existing flake8 workflow, making it easy to catch overly complex type hints during development or CI.

Use it for:

- Enforce a team style guide that discourages deeply nested generics like `Dict[str, List[Tuple[int, Optional[str]]]]` in code review.
- Catch annotation mistakes early—complex annotations often signal bad decomposition or wrong data structure choices.
- Improve code readability by flagging annotations that are hard to parse at a glance.
- Prevent Java-like verbosity in Python type hints during refactoring or new feature development.
- Integrate into CI/CD pipelines to maintain consistent annotation standards across a project.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A flake8 plugin that flags type annotations exceeding configurable complexity thresholds, measuring nesting depth and element count to encourage simpler, more readable type hints.

Yes. The plugin is actively maintained, has no known vulnerabilities, carries a permissive MIT license, and adds minimal install friction (only flake8 as a dependency). It solves a real code-quality problem—catching overly complex type annotations—and integrates seamlessly into existing flake8 workflows. Install it if your team values readable, maintainable type hints.

## Install

pip install flake8-annotations-complexity
uv add flake8-annotations-complexity
poetry add flake8-annotations-complexity

## Installing flake8-annotations-complexity

Before you install: Low friction: pure Python wheel with only flake8 as a runtime dependency. Actively maintained as of 2026-08-14 with no known vulnerabilities.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open and closed projects.

Quickstart:

pip install flake8-annotations-complexity

# In your flake8 config or command line:
flake8 --max-annotations-complexity=3 --max-annotations-len=7 mycode.py

# Reports TAE002 (nesting too deep) and TAE003 (too many elements)

Requires Python 3.10 or later; flake8 must be installed and configured.

Verify before relying:

- Whether the plugin integrates seamlessly with existing flake8 configurations and CI/CD pipelines.
- Performance impact on large codebases with many type annotations.

## Package facts

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

## Tags

flake8 type annotation complexity, check annotation nesting depth, enforce simpler type hints, annotation length linter, reduce annotation complexity, flake8 annotation checker, type hint quality tool, linting, type-hints, code-quality

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