خطای NameError در پایتون؛ name is not defined یعنی چه و چطور رفع می‌شود؟

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

پیام NameError: name '...' is not defined یعنی پایتون نامی را در کد شما دیده که هیچ تعریفی از آن پیدا نکرده است. این نام می‌تواند یک متغیر، تابع، کلاس یا ماژول باشد. این خطا بسیار رایج است و تقریباً همیشه دلیلش یک غلط تایپی، ترتیب اشتباه کد یا فراموش کردن import است.

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

در پایتون قبل از استفاده از هر نامی، باید آن را تعریف کنید؛ یعنی مقداری به متغیر بدهید، تابع را با def بسازید یا ماژول را import کنید. وقتی پایتون در زمان اجرا به نامی برسد که در محدوده (Scope) فعلی و محدوده‌های بالاتر وجود ندارد، خطای NameError می‌دهد. برخلاف SyntaxError، این خطا در زمان اجرا رخ می‌دهد؛ پس خطوط قبل از آن اجرا شده‌اند.

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

• غلط تایپی در نام متغیر یا تابع (پایتون به بزرگی و کوچکی حروف حساس است: Name با name فرق دارد).
• استفاده از متغیر قبل از تعریف آن.
• فراموش کردن کوتیشن دور یک رشته؛ مثلاً print(hello) به جای print("hello").
• فراموش کردن import ماژول، مثل استفاده از math.sqrt بدون import math.
• تعریف متغیر داخل تابع و استفاده از آن بیرون تابع.

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

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

مثال 1: غلط تایپی و حساسیت به حروف

❌ کد غلط:

user_name = "Ali"
print(User_name)

خروجی:

Traceback (most recent call last):
  File "/home/user/project/main.py", line 2, in <module>
    print(User_name)
          ^^^^^^^^^
NameError: name 'User_name' is not defined. Did you mean: 'user_name'?

✅ کد درست:

user_name = "Ali"
print(user_name)

خروجی:

Ali

مثال 2: رشته بدون کوتیشن

❌ کد غلط:

print(hello)

خروجی:

Traceback (most recent call last):
  File "/home/user/project/main.py", line 1, in <module>
    print(hello)
          ^^^^^
NameError: name 'hello' is not defined. Did you mean: 'help'?

✅ کد درست:

print("hello")

خروجی:

hello

مثال 3: فراموش کردن import

❌ کد غلط:

print(math.sqrt(25))

خروجی:

Traceback (most recent call last):
  File "/home/user/project/main.py", line 1, in <module>
    print(math.sqrt(25))
          ^^^^
NameError: name 'math' is not defined. Did you forget to import 'math'?

✅ کد درست:

import math

print(math.sqrt(25))

خروجی:

5.0

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

1. نامی که داخل کوتیشن پیام خطا آمده را دقیقاً در کد جست‌وجو کنید.
2. املای آن را با جایی که تعریفش کرده‌اید مقایسه کنید (حروف بزرگ و کوچک را هم).
3. مطمئن شوید تعریف متغیر یا تابع قبل از خط استفاده قرار دارد.
4. اگر نام مربوط به ماژول است، دستور import را در ابتدای فایل اضافه کنید.
5. اگر متغیر داخل تابع تعریف شده، آن را با return برگردانید یا به عنوان آرگومان پاس دهید.

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

NameError با پیام name is not defined یعنی پایتون نامی را در هیچ‌کدام از محدوده‌ها (محلی، سراسری و داخلی) پیدا نکرده است. علت می‌تواند غلط املایی، استفاده از متغیر قبل از تعریف، فراموش کردن import یا نوشتن رشته بدون کوتیشن باشد. پایتون 3.13 اغلب نام مشابه را با Did you mean پیشنهاد می‌دهد.

ترتیب اجرا مهم است: پایتون کد را از بالا به پایین اجرا می‌کند، پس متغیر یا تابعی که پایین‌تر تعریف شده هنوز وجود ندارد. در Jupyter این خطا وقتی هم رخ می‌دهد که سلول تعریف را اجرا نکرده باشید یا kernel را ری‌استارت کرده باشید. حالت خاص آن UnboundLocalError است.

غلط املایی، ترتیب تعریف و import

user_name = "Sara"

try:
    print(username)
except NameError as error:
    print(type(error).__name__, "-", error)

try:
    print(math.pi)
except NameError as error:
    print(type(error).__name__, "-", error)

import math
print("pi:", round(math.pi, 2), "user:", user_name)

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

NameError - name 'username' is not defined
NameError - name 'math' is not defined
pi: 3.14 user: Sara

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

پایتون نام را در هیچ محدوده‌ای پیدا نکرده؛ ببینید چرا.

1. املای نام را مقایسه کنید: پیشنهاد Did you mean را بخوانید و حروف بزرگ و کوچک را چک کنید.
2. ترتیب اجرا را بررسی کنید: آیا تعریف متغیر یا تابع پایین‌تر از محل استفاده است؟
3. import ها را چک کنید: برای نام ماژول‌ها مثل math یا os، مطمئن شوید import در بالای فایل هست.
4. مسیرهای شرطی را ببینید: اگر متغیر فقط داخل یک if تعریف شده، در مسیر دیگر وجود ندارد.
5. محدوده تابع را بررسی کنید: متغیر محلی یک تابع در تابع دیگر دیده نمی‌شود؛ آن را به‌عنوان آرگومان یا return منتقل کنید.

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

• از ویرایشگری با تکمیل خودکار استفاده کنید تا غلط املایی نام‌ها کم شود.
• همه import ها را در بالای فایل بنویسید.
• متغیرها را قبل از if و حلقه مقدار اولیه بدهید تا در همه مسیرها تعریف شده باشند.
• در Jupyter بعد از ری‌استارت، سلول‌ها را به ترتیب با Run All اجرا کنید.
• از linter مثل ruff یا pyflakes استفاده کنید تا نام‌های تعریف‌نشده قبل از اجرا گزارش شوند.

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

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

فرق NameError با AttributeError چیست؟

NameError یعنی خود نام وجود ندارد؛ AttributeError یعنی شیء وجود دارد ولی ویژگی یا متدی که صدا زده‌اید را ندارد (مثل "abc".push()).

چرا در Jupyter بعد از ری‌استارت NameError می‌گیرم؟

با ری‌استارت کرنل همه متغیرها پاک می‌شوند. سلول‌هایی که متغیرها را تعریف می‌کنند را دوباره به ترتیب اجرا کنید.

آیا متغیر داخل حلقه for بیرون از حلقه قابل استفاده است؟

بله؛ در پایتون متغیر حلقه بعد از پایان حلقه هم وجود دارد، به شرط آنکه حلقه حداقل یک بار اجرا شده باشد. اما متغیرهای داخل تابع بیرون از تابع در دسترس نیستند.

UnboundLocalError چه ارتباطی با NameError دارد؟

زیرکلاس NameError است و وقتی رخ می‌دهد که داخل تابع به متغیری مقدار بدهید و قبل از آن بخوانیدش؛ با global یا ارسال آرگومان رفع می‌شود.

چرا متغیری که داخل if تعریف کردم بیرون شناخته نمی‌شود؟

اگر شرط برقرار نبوده، خط تعریف اصلاً اجرا نشده؛ قبل از if مقدار پیش‌فرض بدهید.

name 'true' is not defined چطور رفع می‌شود؟

در پایتون مقادیر منطقی True و False با حرف بزرگ شروع می‌شوند و None هم همین‌طور.

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

• متغیرها در پایتون
• محدوده متغیرها (local و global)
• ماژول‌ها و پکیج‌ها در پایتون
• آموزش جامع پایتون از صفر تا پیشرفته
• همه خطاهای رایج پایتون و راه‌حل آن‌ها