}

Fix Python IndentationError and TabError: Tabs vs Spaces (2026)

Last updated: 4 min read

IndentationError: unexpected indent

Python uses indentation to define code blocks. An IndentationError means a line is indented when it should not be, or its indentation level does not match the block it belongs to. The immediate fix is to align the offending line with the block it is part of, using 4 spaces per level.

# BROKEN
x = 1
    y = 2   # IndentationError: unexpected indent

# CORRECT
x = 1
y = 2

Last updated: March 2026

The Full Error Messages

IndentationError: unexpected indent
IndentationError: expected an indented block
IndentationError: unindent does not match any outer indentation level
TabError: inconsistent use of tabs and spaces in indentation

All four are subclasses of SyntaxError. Your program will not run at all — Python raises this error during parsing, before executing any code.

Python's Indentation Rules

  1. Each block must be consistently indented. All statements in the same block must have the same number of leading spaces.
  2. Blocks are opened by a colon. if, else, elif, for, while, def, class, with, and try all end with : and require an indented block below.
  3. Dedentation must match a previous level. When you un-indent, you must return to an indentation level that was used for an outer block.
  4. Tabs and spaces must not be mixed. Python 3 raises TabError if it finds both in the same file.
# IndentationError: expected an indented block
def greet():
    # comment here, but no real statement
# This function body is empty — use 'pass' as placeholder

def greet():
    pass   # CORRECT

# IndentationError: unindent does not match
if True:
    x = 1
  y = 2   # 2 spaces — does not match 4-space outer or 0-space top-level

Tabs vs Spaces: PEP 8 Rules

PEP 8 — the official Python style guide — mandates:

  • Use 4 spaces per indentation level.
  • Never mix tabs and spaces. Python 3 makes this a hard error (TabError). Python 2 allowed mixing (with confusing semantics), but Python 3 forbids it entirely.

The root cause of most TabError issues is copying code from different sources — a terminal, a website, a colleague's editor — that use different whitespace conventions. Visually, a tab and 8 spaces can look identical, but Python treats them differently.

Detecting Mixed Indentation

python -tt (Python 2 legacy check)

In Python 2, you could run python -tt script.py to treat tab/space mixing as an error. In Python 3, the interpreter always errors on mixing, so this flag is less necessary — but useful for auditing Python 2 codebases.

Show invisible characters in your terminal

cat -A script.py   # shows ^ for control chars, tabs appear as ^I

grep for tabs

grep -Pn "\t" script.py   # print lines that contain a literal tab character

Fix in VS Code

VS Code makes it easy to convert indentation across a whole file.

  1. Open the file.
  2. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) to open the Command Palette.
  3. Type Convert Indentation to Spaces and press Enter.
  4. Save the file.

To set VS Code to always use spaces for Python files, add to settings.json:

{
    "[python]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 4,
        "editor.detectIndentation": false
    }
}

"editor.detectIndentation": false prevents VS Code from overriding your setting when it detects existing tabs in a file.

Fix in Vim

Convert tabs to spaces for the current file

:set expandtab
:set tabstop=4
:set shiftwidth=4
:%retab!

:set expandtab tells Vim to insert spaces when you press Tab. :%retab! re-indents the entire file using the current tabstop setting, converting existing tabs to spaces.

Make the setting permanent in ~/.vimrc

autocmd FileType python setlocal expandtab tabstop=4 shiftwidth=4

Fix with .editorconfig

.editorconfig is a cross-editor configuration file that many editors (VS Code, Vim with the editorconfig plugin, PyCharm, Sublime Text) respect automatically. Place it at the root of your project:

# .editorconfig
root = true

[*.py]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

With this file present, any editor that supports EditorConfig will automatically use 4-space indentation for .py files — preventing the problem at the source.

Fix with autopep8 or black

Both popular Python formatters will correct indentation automatically.

pip install black
black script.py   # reformats in place, always uses 4-space indentation

pip install autopep8
autopep8 --in-place script.py

Using a formatter in a pre-commit hook or CI pipeline eliminates indentation errors from your codebase entirely.

FAQ

Q: My code looks correctly indented, but Python still raises IndentationError.

A: There are invisible tab characters mixed with spaces. Use cat -A script.py or your editor's "show whitespace" option to make tabs visible. Then run black script.py to fix all indentation automatically.

Q: I copied code from a website and now I get IndentationError.

A: Websites often convert tabs to a non-standard number of spaces or use HTML entities. Paste into a plain-text editor first, or use black to reformat after pasting.

Q: My code works when I run it directly but fails when it is imported as a module.

A: Python re-parses the file on import. If the file has inconsistent indentation that Python 3 only catches during full parsing, it may surface on import. The fix is the same — check for mixed tabs/spaces and reformat.

Related Pages