flake8-annotations

What it is and what it does

flake8-annotations is a Flake8 plugin that scans Python function definitions and reports missing type annotations according to PEP 3107. It detects absent annotations on function parameters (including *args and **kwargs), method self/cls arguments, and return types across public, protected, and special methods. The plugin integrates directly into Flake8's linting pipeline and runs automatically once installed.

The plugin does not replace static type checkers like mypy, does not validate type comments or variable annotations, and does not read stub files. It offers configurable warnings with sensible defaults—most checks enabled by default, opinionated checks (like disallowing typing.Any) disabled by default. Configuration options allow suppressing errors for functions without returns, dummy arguments, untyped nested functions, and functions decorated with dispatch or overload decorators.

Use it for:

• Enforce consistent annotation practices across a team's codebase by failing CI when functions lack type hints.
• Gradually migrate an unannotated legacy codebase toward full type coverage by identifying all missing annotations in one pass.
• Catch untyped *args and **kwargs in function signatures before they cause type-checking issues downstream.
• Suppress annotation requirements for dispatch functions (singledispatch, singledispatchmethod) that intentionally omit hints on the base implementation.
• Detect missing return type hints on public APIs to improve IDE autocomplete and documentation generation.

Worth the install?

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

A Flake8 plugin that enforces PEP 3107-style function type annotations by detecting missing parameter and return type hints in Python code.

Yes. The plugin is actively maintained, has no known vulnerabilities, integrates seamlessly into Flake8 workflows with low install friction, and solves a real problem—enforcing annotation discipline—that static type checkers alone do not address. The MIT license imposes no restrictions. Install it if your team wants to mandate or gradually adopt type annotations.

Install

flake8-annotations on PyPI

pip install flake8-annotations

uv add flake8-annotations

poetry add flake8-annotations

Installing flake8-annotations

Before you install

Low friction: pure Python wheel with only flake8 as a runtime dependency. Actively maintained with a recent commit on 2026-07-10 and no known vulnerabilities.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open and proprietary projects with minimal obligations.

Quickstart

pip install flake8-annotations

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

# Verify it's loaded
flake8 --version

Requires Python 3.10 or later; flake8 must already be installed.

Verify before relying

• Whether the plugin's performance scales acceptably on large codebases with thousands of functions.
• How well the opinionated warnings (ANN401, ANN402) integrate with existing type-checking workflows beyond flake8.

Package facts

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

Tags

More Python Modules packages