Flake8 Commas

4.0.0 · active · verified Thu Apr 16

Flake8 Commas is a plugin for the Flake8 linter that enforces consistent use of trailing commas in Python code. It helps developers avoid annoying merge conflicts when working with multi-line dictionaries, lists, and function calls. The current version is 4.0.0, and as a Flake8 plugin, its release cadence is tied to the broader Flake8 ecosystem.

Common errors

```
IndexError: list index out of range (during flake8 execution)
```
cause Older versions of `flake8-commas` (pre-4.0.0 / pre-`flake8-commas-x`) were incompatible with Python 3.12 due to changes in Python's AST tokenization.

fix Upgrade to `flake8-commas` version 4.0.0 or newer. If `flake8-commas-x` was installed, uninstall it first: `pip uninstall flake8-commas-x && pip install --upgrade flake8-commas`.
```
C818 trailing comma on bare tuple prohibited
```
cause This error occurs when a trailing comma is used on a 'bare' (unparenthesized) tuple, which can lead to unexpected type interpretation in Python (e.g., `value = 1, 2,` is a tuple).

fix Remove the trailing comma for bare assignments that are not explicitly intended as tuples, or explicitly enclose the tuple in parentheses if that is the desired type: `value = 1, 2` or `value = (1, 2, 3,)`.
```
Flake8 is not recognizing flake8-commas plugin / Flake8 does not report C8xx errors
```
cause The `flake8-commas` package is likely installed in a different Python environment than where `flake8` is being executed, or there's a lingering conflict from the `flake8-commas-x` migration.

fix Ensure both `flake8` and `flake8-commas` are installed in the *same* active Python environment. Verify using `pip list` and `flake8 --version`. If previously using `flake8-commas-x`, explicitly uninstall it (`pip uninstall flake8-commas-x`) before reinstalling `flake8-commas` (`pip install --upgrade flake8-commas`).

Warnings

breaking The project was temporarily renamed to `flake8-commas-x` for versions 3.x.x, then renamed back to `flake8-commas` in version 4.0.0. If you are upgrading from `flake8-commas-x`, you *must* uninstall `flake8-commas-x` before installing `flake8-commas` to avoid conflicts.
Fix: pip uninstall flake8-commas-x && pip install flake8-commas
breaking Version 3.0.0 (released as `flake8-commas-x`) dropped support for Python versions older than 3.8 and removed explicit `noqa` handling, as `flake8` now manages this directly.
Fix: Ensure your project uses Python 3.8 or newer. Update your `flake8` configuration if you relied on `flake8-commas`'s specific `noqa` handling.
gotcha Different Python versions have varying requirements and conventions for trailing commas. Flake8 Commas reports specific error codes (e.g., C813 for Python 3, C815 for 3.5+, C816 for 3.6+) based on these differences.
Fix: Configure your `.flake8`, `setup.cfg`, or `pyproject.toml` to ignore error codes for Python versions not used in your project (e.g., `ignore = C814,C815,C816` if only targeting Python 3.8+).
gotcha For a period, `flake8-commas` was unmaintained, with recommendations to use automatic formatters like Black or `add-trailing-comma`. While the project is now actively maintained again (v4.0.0+), automatic formatters offer a different approach to comma enforcement.
Fix: Evaluate if you prefer a linter (flake8-commas) for reporting issues or an auto-formatter (Black, add-trailing-comma) for automatically fixing them. Both approaches can coexist, but ensure consistency in your tooling.

Install

pip install flake8-commas Install latest version

Quickstart

After installing flake8-commas, simply run the `flake8` command on your Python files. The plugin will automatically integrate and report comma-related errors, such as missing trailing commas (e.g., C812) or prohibited trailing commas on bare tuples (C818).

print('Checking for comma errors...')
# example.py
def my_function(
    arg1,
    arg2
): # C812: missing trailing comma
    pass

my_list = [
    1,
    2
] # C812: missing trailing comma

my_dict = {
    'key1': 'value1',
    'key2': 'value2'
} # C812: missing trailing comma

# This will trigger C818: trailing comma on bare tuple prohibited
accidental_tuple = 'item1', 'item2', 

# To run flake8-commas:
# 1. Save the above code to a file named 'example.py'
# 2. Run from your terminal:
#    flake8 example.py

view raw JSON →