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

# flake8-annotations — Flake8 Type Annotation Checks

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

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

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

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

## Tags

flake8 type annotation linter, enforce function type hints, missing annotation detection, pep 3107 compliance, function signature type checking, python annotation linting, flake8 plugin type hints, type-hints, linting, flake8-plugin

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