خطای TabError در پایتون؛ inconsistent use of tabs and spaces in indentation

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

گاهی کدی که کاملاً مرتب به نظر می‌رسد با خطای TabError: inconsistent use of tabs and spaces in indentation اجرا نمی‌شود. دلیلش این است که بعضی خطوط با کاراکتر Tab و بعضی با Space تورفتگی دارند؛ تفاوتی که با چشم دیده نمی‌شود ولی پایتون آن را تشخیص می‌دهد.

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

پایتون ۳ اجازه نمی‌دهد در تورفتگی یک بلوک، Tab و Space را به شکلی ترکیب کنید که معنای آن به عرض Tab بستگی داشته باشد. چون یک Tab در ویرایشگرهای مختلف ممکن است ۲، ۴ یا ۸ فاصله نمایش داده شود، پایتون برای جلوگیری از ابهام این حالت را خطا می‌داند. TabError زیرمجموعه IndentationError است و پیش از اجرای برنامه رخ می‌دهد.

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

• کپی کردن کد از سایت، PDF یا پیام‌رسان که Tab دارد، در فایلی که با Space نوشته شده است.
• کار چند نفر روی یک فایل با تنظیمات ویرایشگر متفاوت.
• ویرایش فایل با Notepad یا ویرایشگری که Tab واقعی درج می‌کند.

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

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

مثال 1: ترکیب Tab و Space (Tab با \t نشان داده شده)

❌ کد غلط:

def total(a, b):
    result = a + b
⇥   return result

خروجی:

  File "/home/user/project/main.py", line 3
    ⇥   return result
    ^
TabError: inconsistent use of tabs and spaces in indentation

✅ کد درست:

def total(a, b):
    result = a + b
    return result

print(total(2, 3))

خروجی:

5

تبدیل همه Tabها به Space در VS Code

در VS Code پایین پنجره روی گزینه Spaces: 4 یا Tab Size کلیک کنید و Convert Indentation to Spaces را بزنید. برای جلوگیری دائمی، در تنظیمات گزینه Insert Spaces را روشن و Render Whitespace را روی all بگذارید تا Tabها به شکل فلش دیده شوند. در خط فرمان هم می‌توانید با python -m tabnanny file.py خطوط مشکل‌دار را پیدا کنید.

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

1. خطی که در پیام خطا آمده و خطوط هم‌بلوک آن را انتخاب کنید.
2. نمایش فاصله‌های نامرئی را در ویرایشگر روشن کنید تا Tabها را ببینید.
3. کل فایل را با گزینه Convert Indentation to Spaces به Space تبدیل کنید.
4. ویرایشگر را طوری تنظیم کنید که کلید Tab چهار Space درج کند.
5. در پروژه‌های تیمی یک فایل .editorconfig با indent_style = space اضافه کنید.

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

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

شماره خطی که در پیام خطا آمده معمولاً همان خطی است که نوع تورفتگی‌اش با خط قبلی فرق دارد. سریع‌ترین راه تشخیص، روشن کردن نمایش کاراکترهای نامرئی (Render Whitespace) در ویرایشگر است؛ Tab به شکل فلش و Space به شکل نقطه دیده می‌شود. می‌توانید با کد زیر هم خط‌های دارای Tab را در یک فایل پیدا کنید.

پیدا کردن خط‌هایی که Tab دارند

source = "def greet():\n    print('hi')\n\tprint('bye')\n"

for number, line in enumerate(source.splitlines(), start=1):
    if line.startswith("\t"):
        print("Tab found on line", number)

try:
    compile(source, "demo.py", "exec")
except TabError as error:
    print(type(error).__name__, "-", error.msg)

fixed = source.replace("\t", "    ")
compile(fixed, "demo.py", "exec")
print("Fixed source compiles")

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

Tab found on line 3
TabError - inconsistent use of tabs and spaces in indentation
Fixed source compiles

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

چون تفاوت Tab و Space دیده نمی‌شود، باید کاراکترهای نامرئی را آشکار کنید.

1. شماره خط پیام را یادداشت کنید: آن خط و خط بالای آن را مقایسه کنید؛ معمولاً یکی Tab دارد و دیگری Space.
2. نمایش فاصله‌ها را روشن کنید: در VS Code گزینه Render Whitespace را روی all بگذارید تا Tab به شکل فلش دیده شود.
3. کل فایل را بررسی کنید: با python -m tabnanny file.py خط‌های مبهم از نظر تورفتگی گزارش می‌شوند.
4. یکدست‌سازی کنید: دستور Convert Indentation to Spaces را اجرا کنید یا در کد از source.replace(‘\t’, ‘ ‘) استفاده کنید.
5. تنظیم را ماندگار کنید: Insert Spaces و Tab Size برابر 4 را در تنظیمات ویرایشگر و فایل .editorconfig ذخیره کنید.

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

• در ویرایشگر گزینه Insert Spaces را فعال کنید تا کلید Tab چهار فاصله درج کند.
• طبق PEP 8 همیشه از چهار Space برای هر سطح تورفتگی استفاده کنید.
• هنگام کپی کد از سایت‌ها یا PDF، فایل را با Convert Indentation to Spaces یکدست کنید.
• یک فایل .editorconfig در پروژه بگذارید تا همه اعضای تیم تنظیم یکسان داشته باشند.
• از فرمت‌کننده‌هایی مثل black یا ruff format استفاده کنید تا تورفتگی خودکار اصلاح شود.

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

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

Tab بهتر است یا Space؟

راهنمای رسمی PEP 8 استفاده از ۴ Space را توصیه می‌کند و تقریباً همه پروژه‌های پایتون از Space استفاده می‌کنند.

آیا فایلی که فقط با Tab نوشته شده خطا می‌دهد؟

خیر؛ اگر کل فایل به‌طور یکدست با Tab باشد کار می‌کند. مشکل فقط از ترکیب ناسازگار Tab و Space پیش می‌آید.

چرا کد در ویرایشگر مرتب است ولی خطا می‌دهد؟

چون Tab و Space ممکن است در ظاهر یکسان دیده شوند. با روشن کردن نمایش فاصله‌ها تفاوت را می‌بینید.

فرق TabError و IndentationError چیست؟

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

در VS Code چطور همه Tab ها را به Space تبدیل کنم؟

از Command Palette دستور Convert Indentation to Spaces را اجرا کنید و در نوار پایین Spaces: 4 را انتخاب کنید.

آیا استفاده از فقط Tab در کل فایل مجاز است؟

از نظر فنی بله، به شرط اینکه هیچ Space ای قاطی نشود؛ اما استاندارد جامعه پایتون چهار فاصله است و بهتر است از آن پیروی کنید.

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

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