یکی از متداول‌ترین خطاهایی که هر برنامه‌نویس پایتون — مخصوصاً تازه‌کارها — تجربه می‌کند، خطای IndentationError است. برخلاف بسیاری از زبان‌های برنامه‌نویسی، پایتون از تورفتگی (indentation) برای مشخص‌کردن ساختار کد استفاده می‌کند، نه از علامت‌هایی مثل {}. به همین دلیل، کوچک‌ترین اشتباه در تعداد فاصله‌ها یا ترکیب فاصله و تب (Tab) می‌تواند باعث توقف اجرای برنامه شود. در این مقاله بررسی می‌کنیم که چرا خطای IndentationError رخ می‌دهد، چطور می‌توان آن را شناسایی کرد و بهترین روش‌های رفع آن چیست.

خطای IndentationError چیست؟

در پایتون، تورفتگی مشخص می‌کند که بلوک‌های کد مثل حلقه‌ها، شرط‌ها و توابع به کدام بخش تعلق دارند.
وقتی این ساختار از دید مفسر پایتون ناهماهنگ باشد، خطای IndentationError نمایش داده می‌شود.

به‌عنوان مثال، کد زیر باعث بروز خطا می‌شود:

for i in range(5):
print(i)

خروجی خطا در کنسول:

IndentationError: expected an indented block

چون دستور print(i) باید با تورفتگی نسبت به حلقه for نوشته شود.

دلایل رایج بروز خطای IndentationError

۱. نداشتن تورفتگی بعد از دستورهای کنترلی

هر دستوری که با : تمام می‌شود (مثل if، for، while، def، class) باید بدنه‌ی خودش را با حداقل یک سطح تورفتگی آغاز کند.
مثلاً:

if True:
print("Hello")

خطا می‌دهد.

درست:

if True:
    print("Hello")

۲. ترکیب فاصله (Space) و تب (Tab) در یک فایل

پایتون بین تب و فاصله تفاوت قائل است.
اگر بخشی از کد با تب و بخش دیگر با فاصله نوشته شده باشد، خطایی مثل زیر رخ می‌دهد:

IndentationError: unindent does not match any outer indentation level

راه‌حل: همیشه از یک نوع تورفتگی ثابت استفاده کنید (ترجیحاً ۴ فاصله در هر سطح).
در VS Code یا PyCharm می‌توان تنظیم کرد که تب‌ها خودکار به فاصله تبدیل شوند.

۳. تورفتگی اشتباه هنگام خروج از بلوک

گاهی هم تورفتگی بیش از حد باعث خطا می‌شود.

def greet():
    print("Hi!")
        print("Welcome!")

پایتون انتظار دارد خطوط داخلی تابع تورفتگی برابر داشته باشند، اما در این مثال خط دوم بیش از حد تو رفته است.

۴. کپی و پیست از منابع مختلف

وقتی کد را از اینترنت یا ویرایشگرهای متفاوت کپی می‌کنی، ممکن است تب‌ها و فاصله‌ها به‌صورت نامرئی درهم‌ریخته باشند.
حتی اگر ظاهر کد درست باشد، مفسر پایتون آن را ناسازگار می‌داند.

راه‌ حل: کل متن را انتخاب و در ویرایشگر خود با دستور

Convert Indentation to Spaces

پاک‌سازی کن.

۵. دستورات تک‌خطی بدون بدنه

اگر دستور کنترلی (if, for, while) بدون بدنه باشد، حتی اگر قصد اجرای عملی نداشته باشی، باید از کلمه‌ی کلیدی pass استفاده کنی.

for i in range(3):

خطا می‌دهد.

درست:

for i in range(3):
    pass

انواع خطاهای مرتبط با Indentation در پایتون

نوع خطا توضیح مثال
IndentationError: expected an indented block بعد از : تورفتگی وجود ندارد بعد از if یا for بدنه‌ای نوشته نشده
IndentationError: unexpected indent تورفتگی در جایی که نباید هست کد اشتباهی تو رفته
IndentationError: unindent does not match any outer indentation level سطح تورفتگی با خطوط قبلی هم‌خوانی ندارد ترکیب تب و فاصله در یک فایل

چطور بفهمیم مشکل از کجاست؟

در محیط‌های توسعه (IDE) مثل VS Code، PyCharm یا Jupyter Notebook معمولاً خطا با رنگ یا خط قرمز زیر کد مشخص می‌شود.
اما اگر در ترمینال کار می‌کنی، خطا معمولاً شماره خط را هم نشان می‌دهد.
برای مثال:

File "main.py", line 7
    print("Hello")
    ^
IndentationError: unexpected indent

یعنی در خط ۷ تورفتگی غیرمنتظره وجود دارد.

روش‌ های رفع IndentationError

۱. استفاده از ویرایشگر حرفه‌ای

از ویرایشگرهایی استفاده کن که نمایش تورفتگی و فضاهای سفید را فعال می‌کنند.
در VS Code می‌توانی گزینه‌ی “Render Whitespace” را فعال کنی تا تب‌ها و فاصله‌ها قابل‌مشاهده شوند.

۲. یک‌ دست‌ سازی تنظیمات تورفتگی

در تنظیمات محیط توسعه، حالت زیر را انتخاب کن:

Tab size: 4
Insert spaces: True

۳. پاک کردن تورفتگی و تنظیم مجدد

گاهی ساده‌ترین روش رفع خطا این است که همه‌ی تورفتگی‌های مشکوک را حذف و مجدداً اضافه کنی.

۴. استفاده از ابزارهای خودکار قالب‌بندی

ابزارهایی مثل Black، Autopep8 یا yapf می‌توانند به‌صورت خودکار کد را بر اساس استاندارد PEP8 قالب‌بندی کنند و مشکلات تورفتگی را برطرف سازند.

 

نکته‌ پیشرفته: تفاوت IndentationError و TabError

در نسخه‌های جدید پایتون، اگر مشکل دقیقاً از مخلوط شدن تب و فاصله باشد، ممکن است به‌جای IndentationError خطای TabError ببینی.
مثلاً:

TabError: inconsistent use of tabs and spaces in indentation

در این حالت راه‌حل ساده است: کل کد را با تبدیل همه‌ی تب‌ها به فاصله اصلاح کن.

جمع بندی

خطای IndentationError در پایتون یکی از ساده‌ترین ولی شایع‌ترین خطاهاست.
دلیل اصلی آن، بی‌نظمی در تورفتگی‌هاست — چه به‌خاطر فراموشی، چه کپی از منابع مختلف.
اگر ساختار تورفتگی را یک‌دست نگه داری (ترجیحاً ۴ فاصله برای هر سطح)، از این خطا خلاص می‌شوی.
یادت باشد در پایتون، زیبایی کد یعنی نظم در تورفتگی.