flake8-builtins

What it is and what it does

flake8-builtins is a flake8 plugin that catches a common Python mistake: shadowing built-in names (like `list`, `dict`, `max`, `zip`) with your own variables, function parameters, class attributes, or imports. When you shadow a builtin, you lose access to it in that scope, which can cause cryptic TypeErrors or other runtime failures. The plugin runs as part of your flake8 linting workflow and reports six categories of violations (A001–A006) for different kinds of shadowing.

It works by integrating into flake8's AST visitor and checking each name binding against Python's builtins. You can customize which builtins to ignore via the --builtins-ignorelist option if you have a legitimate reason to shadow a specific builtin. The plugin supports Python 3.10, 3.11, 3.12, 3.13, 3.14, and PyPy3.

Use it for:

• Catch accidental shadowing of builtins like `list` or `dict` in function parameters before they cause runtime errors.
• Enforce a team code-style rule that forbids shadowing builtins to keep code predictable and maintainable.
• Integrate into CI/CD pipelines to reject pull requests that introduce builtin shadowing violations.
• Audit legacy codebases for places where builtins have been shadowed and need refactoring.
• Whitelist specific builtins you intentionally shadow (e.g., `id` or `copyright`) via configuration.

Worth the install?

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

A flake8 plugin that detects when Python builtins are shadowed by variables, parameters, class attributes, imports, or lambda arguments in your code.

Yes, if you use flake8 and want to prevent a class of subtle bugs. The plugin is lightweight, has no external dependencies beyond flake8, and catches real mistakes that can break code at runtime. Maintenance is aging but the package is stable and widely used (nearly 1 million monthly downloads). No known security vulnerabilities.

Install

flake8-builtins on PyPI

pip install flake8-builtins

uv add flake8-builtins

poetry add flake8-builtins

Installing flake8-builtins

Before you install

Installs with minimal friction—a pure Python wheel with only flake8 as a runtime dependency. Maintenance status is aging (last release 293 days ago), but the repository remains active and the package is marked Production/Stable.

License in practice

Licensed under GPLv2 (copyleft). If you distribute code that uses this plugin, you must make your modifications available under the same license; this applies primarily to derivative works of the plugin itself, not to code you lint with it.

Quickstart

pip install flake8-builtins

flake8 --builtins-ignorelist id,copyright myfile.py

Verify before relying

• Whether the plugin is actively maintained or in maintenance-only mode given the 293-day gap since last release.
• Whether the --builtins-ignorelist option works as documented in current versions.

Package facts

Evidence: flake8_builtins-3.1.0-py3-none-any.whl

Keywords: flake8, pep8, python

Tags

More Software Development packages