Flake8
raw JSON → 7.3.0 verified Sat Apr 11 auth: no python quickstart: stale
Flake8 is a modular source code checker that wraps PyFlakes, pycodestyle, and Ned Batchelder's McCabe script. It runs all these tools with a single command, displaying a merged output of warnings. As of version 7.3.0, it is actively maintained with releases as necessary, often driven by bug fixes and new features.
pip install flake8 Common errors
error ModuleNotFoundError: No module named 'flake8' ↓
cause Flake8 is not installed in the active Python environment or its executable is not found in the system's PATH. This often happens when flake8 is installed in a different virtual environment or globally, but the current environment does not have access to it.
fix
Install flake8 using pip:
pip install flake8 or python -m pip install flake8. error F821 undefined name 'name' ↓
cause The Python code attempts to use a variable, function, or class name that has not been defined or imported in the current scope. This error comes from Pyflakes, which Flake8 wraps.
fix
Ensure the name is defined before its first use, or import it if it's from another module. For forward references in type hints,
from __future__ import annotations (for Python < 3.9) or string literal type hints can be used. error E901 SyntaxError: invalid syntax ↓
cause The Python code contains a fundamental syntax error or an indentation error that prevents the Python interpreter from parsing the file. Flake8 reports this error because it cannot process malformed Python code.
fix
Correct the underlying Python syntax or indentation error in the specified file and line. This is a core Python language error.
error W503 line break before binary operator ↓
cause Pycodestyle, a component of Flake8, flags a style violation where a line break occurs immediately before a binary operator (e.g., `+`, `-`, `*`, `/`). This rule can conflict with preferences or auto-formatters like Black.
fix
To ignore this specific warning, add
--ignore=W503 to the flake8 command-line arguments, or include ignore = W503 or extend-ignore = W503 in your flake8 configuration file (.flake8, setup.cfg, or tox.ini). error flake8: error: no such option: --maxLineLength ↓
cause The command-line option or configuration file entry for setting the maximum line length is misspelled or incorrectly formatted, using camel case instead of hyphens.
fix
Use
--max-line-length in command-line arguments (e.g., flake8 --max-line-length=100 your_file.py) or max-line-length = 100 in a configuration file. Warnings
breaking Flake8 7.0.0 removed the `--include-in-doctest` and `--exclude-from-doctest` options. ↓
fix Review your Flake8 configuration and remove these options if present. Adjust your exclusion patterns using `--exclude` or `exclude` in your config file if you previously relied on doctest-specific exclusions.
breaking Flake8 6.0.0 removed the `--diff` option. It also became stricter, producing errors for invalid codes specified in configuration files or if the file specified in `--extend-config` does not exist. Additionally, Python 3.8.1 or newer is now required. ↓
fix Remove `--diff` from your CI/local scripts. Validate your `.flake8`, `setup.cfg`, or `tox.ini` files for correct error codes and ensure all `--extend-config` paths are valid. Upgrade your Python interpreter to at least 3.8.1.
breaking Major releases (e.g., 3.0, 4.0, 5.0, 6.0, 7.0) historically include large-scale refactoring, 'subtly breaking CLI changes,' and breaking changes to its plugin interface. Always review release notes for new major versions. ↓
fix Before upgrading to a new major version, carefully read the official release notes and migration guides. Test your Flake8 configuration and any custom plugins in a separate environment.
gotcha Flake8's ability to correctly parse Python code is dependent on the Python version it's installed and run with. If you are checking code written with newer Python language features (e.g., Python 3.10's structural pattern matching), Flake8 needs to be installed on a Python 3.10 interpreter to understand those features. ↓
fix Ensure Flake8 is installed and executed using the same Python version that your project code targets. For example, use `python3.10 -m pip install flake8` and then `python3.10 -m flake8 .`
gotcha Flake8 options can be specified on the command-line, or in configuration files (`.flake8`, `setup.cfg`, `tox.ini`). Command-line options always take precedence over configuration file settings. This can lead to unexpected behavior if not understood. ↓
fix When troubleshooting unexpected Flake8 behavior, first check command-line arguments, then project configuration files (in order of `.flake8`, `setup.cfg`, `tox.ini`), and finally default settings. Ensure no command-line options are inadvertently overriding your desired configuration.
gotcha Using `# noqa` comments to ignore errors on a line or file (`# flake8: noqa`) can be convenient but may hide legitimate bugs or style violations, degrading code quality over time if overused. ↓
fix Use `# noqa` sparingly and only for very specific, justified cases. Prefer to fix the underlying issue or configure Flake8's `ignore` or `per-file-ignores` options in a `.flake8` config file for project-wide exclusions, documenting the reason for the exclusion.
gotcha A `SyntaxError: invalid syntax` when attempting to run `flake8 .` (or similar shell commands) directly from a Python script indicates that the command is being interpreted by the Python interpreter itself, rather than executed in a shell environment. Python treats `flake8 .` as invalid syntax. ↓
fix Ensure that shell commands like `flake8 .` are executed in a shell environment (e.g., directly in a shell script, in a CI configuration command, or via Python's `subprocess` module if embedded within a Python script, like `subprocess.run(['flake8', '.'])`).
gotcha The Flake8 command was invoked directly within a Python interpreter, leading to a `SyntaxError`. Flake8 is a command-line tool and should be executed as a shell command (e.g., `flake8 .` or `python -m flake8 .`), not as Python syntax. ↓
fix Ensure Flake8 is executed as a shell command. If running within a Python script, use `subprocess.run(['flake8', '.'])` or `os.system('flake8 .')`. If using a Dockerfile or CI script, execute it directly, e.g., `RUN flake8 .` or `CMD flake8 .`.
Quickstart stale last tested: 2026-04-23
flake8 .