Python "TabError" / "IndentationError" - Tabs vs Spaces in CI

Python is whitespace-sensitive. Mixing tabs and spaces in the same block - often invisible in an editor - makes the parser reject the file with a TabError or IndentationError.

What this error means

The file fails to parse with TabError: inconsistent use of tabs and spaces in indentation or IndentationError: unexpected indent. It frequently surfaces in CI even when it "looked fine" locally because an editor rendered tabs as spaces.

  File "tasks.py", line 22
    return result
                 ^
TabError: inconsistent use of tabs and spaces in indentation

Common causes

Mixed tabs and spaces in one block

Some lines indent with tabs and others with spaces. CPython 3 forbids ambiguous mixing and raises TabError.

Editor settings differ from the repo

A contributor’s editor inserts tabs while the project uses spaces (or vice versa), producing inconsistent indentation that only the parser catches.

How to fix it

Normalize to 4 spaces

PEP 8 uses 4 spaces. Convert tabs and let a formatter enforce it.

# convert tabs to spaces in a file
expand -t 4 tasks.py > tasks.py.tmp && mv tasks.py.tmp tasks.py
# or run a formatter across the project
black .

Catch it in CI before merge

1. Run python -m tabnanny <file> or a linter that flags mixed indentation.
2. Enforce formatting with black --check or ruff format --check in CI.
3. Add an .editorconfig so editors use the project’s indentation.

How to prevent it

• Adopt black or ruff format and check formatting in CI.
• Commit an .editorconfig to standardize indentation.
• Configure editors to insert spaces, not tabs.

Related guides