Содержание
Что означает ошибка NameError: name is not defined в Python?
Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.
Ошибка NameError: name is not defined означает, что Python встретил имя — переменную, функцию, класс или модуль, — которое не определено на момент выполнения этой строки. Исправление сводится к четырём проверкам: опечатка в имени, порядок определения (имя должно появиться в коде раньше использования), область видимости и забытый import. Ниже — каждая причина с примером кода и готовым фиксом.
Что означает NameError
Документация Python определяет NameError так: исключение возникает, когда локальное или глобальное имя не найдено. Это касается только неквалифицированных имён: для x будет NameError, а для несуществующего атрибута obj.x — уже AttributeError. Сообщение об ошибке всегда содержит имя, которое не удалось найти, а начиная с Python 3.10 у исключения есть отдельный атрибут name — подробности в официальной документации.
Типичный traceback выглядит так:
print(x) # Traceback (most recent call last): # File "main.py", line 1, in <module> # print(x) # NameError: name 'x' is not defined
Последняя строка — сама ошибка с именем, которое Python не нашёл. Строкой выше — файл и номер строки, где это произошло. Этих двух строк обычно достаточно, чтобы найти причину.
Причины возникновения NameError
Необъявленная переменная
Самый частый случай: переменная используется, но ей нигде не присвоено значение. Python не знает, что такое x, пока вы не выполните присваивание:
print(x) # NameError: name 'x' is not defined x = 10 # сначала объявляем print(x) # 10
Правило простое: любое имя должно получить значение до первой строки, где оно читается.
Опечатка в имени
Python чувствителен к регистру: count, Count и COUNT — три разных имени. Одна пропущенная буква — и интерпретатор ищет несуществующую переменную:
message = "Привет" print(mesage) # NameError: name 'mesage' is not defined print(message) # исправлено: Привет
Вызов функции до её определения
Скрипт выполняется сверху вниз. Если вызвать функцию выше строки, где она определена, имя ещё не существует:
greet() # NameError: name 'greet' is not defined
def greet():
print("Привет")
greet() # а после определения — работает
Если при этом путаетесь, чем функция отличается от метода, разберитесь в руководстве «Функции против методов в Python».
Строка без кавычек
Без кавычек Python принимает текст за имя переменной и ищет его в памяти:
print(hello) # NameError
print("hello") # исправлено
Область видимости
Переменная, созданная внутри функции, — локальная. За пределами функции её не существует:
def calc():
total = 42
return total
result = calc()
print(result) # 42
print(total) # NameError
Правильный путь — вернуть значение через return и сохранить его в переменную снаружи, как в примере выше. В обратную сторону это работает: глобальную переменную внутри функции читать можно; ключевое слово global нужно, только если функция ей что-то присваивает.
Забытый import
Функции из модулей недоступны, пока модуль не импортирован в этом файле:
value = random.randint(1, 10) # NameError: name 'random' is not defined import random value = random.randint(1, 10) # работает
То же с отдельными именами: после from math import sqrt доступно имя sqrt, но не math. Учтите и обратное: импорт действует только в том файле, где он написан, — в каждом модуле проекта нужен свой import.
Код из Python 2
Отдельный класс случаев — примеры из старых учебников. В Python 3 нет встроенных имён raw_input и xrange, поэтому такой код падает с NameError:
name = raw_input("Имя: ")
# NameError: name 'raw_input' is not defined
name = input("Имя: ") # так в Python 3
Аналогично xrange(10) заменяется на range(10). Если ошибка появилась в чужом коде с GitHub или из книги — первым делом проверьте, под какую версию Python он написан.
Сравнительная таблица причин
| Причина | Как выглядит | Как исправить |
|---|---|---|
| Переменная не объявлена | print(x) без присваивания |
Присвоить значение до использования |
| Опечатка или регистр | mesage вместо message |
Сверить написание, включая регистр |
| Вызов до определения | greet() выше def greet() |
Перенести вызов ниже определения |
| Строка без кавычек | print(hello) |
Добавить кавычки: print("hello") |
| Область видимости | Локальная переменная читается снаружи функции | Вернуть через return или объявить global |
| Нет импорта | random.randint(1, 10) без import |
Добавить import random |
| Код из Python 2 | raw_input(), xrange() |
Заменить на input() и range() |
UnboundLocalError: частный случай NameError
Если внутри функции имени присваивается значение, Python считает его локальным во всей функции — даже в строках выше присваивания. Чтение такой переменной до присваивания даёт UnboundLocalError — по документации это подкласс NameError:
counter = 0
def increment():
print(counter) # UnboundLocalError
counter = 1
increment()
Если функция должна менять глобальную переменную, объявите это явно:
counter = 0
def increment():
global counter
counter += 1
increment()
print(counter) # 1
Для вложенных функций вместо global используется nonlocal.
Подсказки «Did you mean» в Python 3.10+
Начиная с Python 3.10 интерпретатор при выводе NameError сам предлагает похожие имена из той же области видимости:
schwarzschild_black_hole = None schwarschild_black_hole # NameError: name 'schwarschild_black_hole' # is not defined. Did you mean: # schwarzschild_black_hole?
В Python 3.12 подсказки стали шире: при обращении к стандартному модулю без импорта интерпретатор пишет «Did you forget to import ‘sys’?», а внутри метода класса предлагает self.имя, если атрибут с таким именем есть у экземпляра. Нюанс: подсказки формирует стандартный вывод ошибок Python, поэтому в оболочках с собственным отображением ошибок (например, IPython) их может не быть.
Инструменты, которые ловят NameError до запуска
Большинство NameError можно увидеть ещё до выполнения программы:
- PyCharm — подсвечивает неопределённые имена при наборе кода; в отладчике есть точки останова, пошаговое выполнение и просмотр переменных с их областями видимости.
- Visual Studio Code — расширения для Python подсвечивают опечатки в именах и проблемы с областями видимости в реальном времени.
- PyLint — статический анализатор: проверяет код на соответствие PEP 8 и предупреждает о необъявленных переменных и недостающих импортах до запуска.
- ИИ-ассистенты — вставьте полный traceback в чат-бот и получите объяснение с вариантом фикса; примеры такого подхода — в статье «6 примеров того, как ChatGPT поможет начинающему фронтенд-разработчику».
Сам навык чтения ошибок универсален для любого языка: как системно искать причину бага, разбираем в материале «Как поймать баг в коде: отладка в браузере».
Частые вопросы
Чем NameError отличается от AttributeError?
NameError касается неквалифицированных имён (x), AttributeError — атрибутов объекта (obj.x). Если имя слева от точки существует, а справа — нет, будет AttributeError.
Чем NameError отличается от UnboundLocalError?
UnboundLocalError — подкласс NameError. Он возникает, когда локальная переменная функции читается до строки, где ей присвоено значение. Решается через return, global или nonlocal.
Можно ли перехватить NameError через try/except?
Технически да — except NameError: сработает. Но на практике это почти всегда маскировка бага: правильнее исправить причину (объявить переменную, добавить import), а не глушить ошибку.
Почему в Jupyter переменная «пропала»?
После перезапуска ядра все переменные сессии стираются. Ячейки, где они определялись, нужно выполнить заново — иначе обращение к ним снова даст NameError.
Заключение
NameError — одна из первых ошибок, с которой сталкивается любой разработчик на Python, и одна из самых быстрых в исправлении. Алгоритм: прочитать последнюю строку traceback, проверить опечатку и регистр, убедиться, что имя определено выше по коду и в нужной области видимости, добавить недостающий import. А начиная с Python 3.10 интерпретатор сам подсказывает, какое имя вы имели в виду.