خطای IndentationError در پایتون؛ معنی، علت و رفع expected an indented block

🗓 آخرین به‌روزرسانی: 24 مهر 1405

اگر تازه پایتون را شروع کرده‌اید، به احتمال زیاد اولین خطایی که می‌بینید IndentationError است. برخلاف زبان‌هایی مثل جاوا یا C که بلوک‌های کد را با آکولاد {} مشخص می‌کنند، پایتون از «تورفتگی» (فاصله ابتدای خط) برای تشخیص اینکه کدام خطوط داخل یک شرط، حلقه یا تابع هستند استفاده می‌کند. پس فاصله‌ها در پایتون فقط برای زیبایی نیستند؛ بخشی از دستور زبان‌اند.

معنی خطای IndentationError در پایتون

IndentationError یعنی مفسر پایتون انتظار داشته یک خط با تورفتگی مشخصی شروع شود، ولی این‌طور نبوده است. دو پیام رایج این خطا عبارت‌اند از: expected an indented block (بعد از خطی که با دونقطه : تمام شده، خط بعدی تورفتگی ندارد) و unexpected indent (خطی بی‌دلیل جلوتر از بقیه شروع شده است). این خطا قبل از اجرای برنامه و در مرحله خواندن کد رخ می‌دهد؛ بنابراین حتی یک خط از برنامه هم اجرا نمی‌شود.

علت‌های رایج این خطا

• بعد از if، for، while، def یا class خط بعدی را بدون تورفتگی نوشته‌اید.
• یک خط معمولی را بی‌دلیل با چند فاصله جلوتر شروع کرده‌اید (معمولاً هنگام کپی کد از سایت‌ها).
• تعداد فاصله‌های خطوط یک بلوک یکسان نیست؛ مثلاً یک خط ۴ فاصله و خط بعد ۳ فاصله دارد.
• بدنه یک تابع یا شرط را فعلاً خالی گذاشته‌اید و چیزی داخلش ننوشته‌اید.

کد غلط و کد درست (با خروجی واقعی)

همه نمونه‌کدهای زیر با پایتون 3.13.5 اجرا شده‌اند و خروجی‌ها همان چیزی است که پایتون واقعاً نمایش می‌دهد.

مثال 1: فراموش کردن تورفتگی بعد از if

❌ کد غلط:

age = 20
if age >= 18:
print("Adult")

خروجی:

  File "/home/user/project/main.py", line 3
    print("Adult")
    ^^^^^
IndentationError: expected an indented block after 'if' statement on line 2

✅ کد درست:

age = 20
if age >= 18:
    print("Adult")

خروجی:

Adult

مثال 2: تورفتگی اضافه و غیرمنتظره

❌ کد غلط:

name = "Sara"
    print(name)

خروجی:

  File "/home/user/project/main.py", line 2
    print(name)
IndentationError: unexpected indent

✅ کد درست:

name = "Sara"
print(name)

خروجی:

Sara

مثال 3: بدنه خالی تابع

❌ کد غلط:

def calculate():

print("done")

خروجی:

  File "/home/user/project/main.py", line 3
    print("done")
    ^^^^^
IndentationError: expected an indented block after function definition on line 1

✅ کد درست:

def calculate():
    pass  # to be completed later

print("done")

خروجی:

done

راه‌حل قدم‌به‌قدم

1. شماره خطی که در پیام خطا آمده را پیدا کنید؛ مشکل معمولاً در همان خط یا خط قبل از آن است.
2. بررسی کنید آیا خط قبلی با دونقطه : تمام شده است؛ اگر بله، خط فعلی باید جلوتر (معمولاً ۴ فاصله) باشد.
3. مطمئن شوید همه خطوط داخل یک بلوک دقیقاً به یک اندازه تورفتگی دارند.
4. اگر بدنه بلوک را فعلاً ندارید، از دستور pass استفاده کنید.
5. در ویرایشگر (VS Code یا PyCharm) گزینه نمایش فاصله‌ها (Render Whitespace) را روشن کنید و تنظیم کنید که کلید Tab چهار فاصله درج کند.

خواندن پیام IndentationError و عیب‌یابی

پایتون به جای آکولاد، با تورفتگی (indentation) بلوک‌های کد را مشخص می‌کند. IndentationError یعنی تورفتگی خطی با ساختار انتظار‌رفته جور نیست؛ سه پیام رایج آن expected an indented block، unexpected indent و unindent does not match any outer indentation level هستند و هرکدام علت متفاوتی دارند.

expected an indented block یعنی بعد از خطی که با دونقطه تمام شده، بدنه بلوک خالی مانده یا تورفتگی ندارد. unexpected indent یعنی خطی بی‌دلیل جلوتر رفته است. unindent does not match یعنی خطی به سطحی برگشته که با هیچ سطح قبلی برابر نیست، مثلاً سه فاصله به جای چهار. کد زیر هر سه پیام را تولید می‌کند.

سه پیام رایج IndentationError

samples = {
    "empty block": "def f():\nreturn 1",
    "extra indent": "x = 1\n    y = 2",
    "wrong level": "if True:\n    a = 1\n  b = 2",
}

for label, code in samples.items():
    try:
        compile(code, "demo.py", "exec")
    except IndentationError as error:
        print(label, "->", error.msg)

compile("def f():\n    pass", "demo.py", "exec")
print("pass keeps an empty block valid")

خروجی (اجراشده با Python 3.13):

empty block -> expected an indented block after function definition on line 1
extra indent -> unexpected indent
wrong level -> unindent does not match any outer indentation level
pass keeps an empty block valid

قدم‌به‌قدم رفع IndentationError

سه پیام اصلی این خطا هرکدام راه‌حل مشخصی دارند.

1. نوع پیام را مشخص کنید: expected an indented block، unexpected indent یا unindent does not match.
2. برای بلوک خالی: خط بعد از دونقطه را چهار فاصله جلو ببرید یا اگر هنوز کدی ندارید pass بنویسید.
3. برای تورفتگی اضافه: خطی که بی‌دلیل جلوتر رفته را به سطح خط قبلی برگردانید.
4. برای سطح نامعتبر: تعداد فاصله‌ها را بشمارید؛ سطح‌ها باید مضرب 4 و برابر با یکی از سطح‌های قبلی باشند.
5. کل فایل را یکدست کنید: با black یا ruff format تورفتگی را خودکار درست کنید و ترکیب Tab و Space را حذف کنید.

چک‌لیست پیشگیری

• همیشه از چهار فاصله برای هر سطح استفاده کنید و Tab را به Space تبدیل کنید.
• برای بلوک‌هایی که هنوز کد ندارند، از pass استفاده کنید.
• نمایش راهنمای تورفتگی (indent guides) را در ویرایشگر روشن کنید.
• هنگام کپی کد از وب، کل بلوک را انتخاب و با Shift+Tab و Tab یکدست کنید.
• از فرمت‌کننده black یا ruff format استفاده کنید.

📌 همچنین بخوانید: خطای unexpected EOF while parsing در پایتون، خطای ‘int’ object is not subscriptable در پایتون و خطای ImportError

سؤالات متداول

چند فاصله برای تورفتگی در پایتون استاندارد است؟

طبق راهنمای رسمی PEP 8، استاندارد ۴ فاصله برای هر سطح تورفتگی است. پایتون با تعداد دیگری از فاصله‌ها هم کار می‌کند، به شرط آنکه داخل یک بلوک یکسان باشد؛ اما رعایت ۴ فاصله خوانایی کد را بالا می‌برد.

فرق IndentationError با TabError چیست؟

TabError در واقع زیرمجموعه‌ای از IndentationError است و فقط زمانی رخ می‌دهد که در تورفتگی یک بلوک، Tab و Space را به شکل ناسازگار با هم ترکیب کرده باشید.

چرا بعد از کپی کد از اینترنت این خطا را می‌گیرم؟

کدهای کپی‌شده اغلب فاصله‌های نامرئی، Tab یا تورفتگی اضافه در ابتدای خطوط دارند. کد را در ویرایشگر انتخاب کنید و با Shift+Tab تورفتگی‌ها را اصلاح کنید.

unindent does not match any outer indentation level یعنی چه؟

یعنی خطی به سطح تورفتگی برگشته که قبلاً وجود نداشته، مثلاً دو فاصله در حالی که سطح‌ها صفر و چهار بوده‌اند؛ تعداد فاصله‌ها را یکسان کنید.

آیا خط کامنت هم IndentationError می‌دهد؟

خیر، کامنت‌ها و خط‌های خالی در تورفتگی نقشی ندارند؛ اما بلوکی که فقط کامنت دارد همچنان خالی محسوب می‌شود و به pass نیاز دارد.

در مفسر تعاملی چرا این خطا را زیاد می‌بینم؟

چون باید بعد از پایان بلوک یک خط خالی بزنید و تورفتگی را دستی وارد کنید؛ برای کدهای چندخطی از فایل استفاده کنید.

آموزش‌های مرتبط

• شرط‌ها در پایتون (if، elif، else)
• حلقه for در پایتون
• تعریف تابع با def و return
• آموزش جامع پایتون از صفر تا پیشرفته
• همه خطاهای رایج پایتون و راه‌حل آن‌ها