Python NameError

3NameError: explained step by step

A NameError means Python met a name (a variable, function or module) that it has never heard of at that moment. The message always quotes the culprit: NameError: name 'totl' is not defined. Nothing is wrong with the line's grammar; Python simply looked for that name and found nothing.

What "name is not defined" really means

When Python reads a name, it searches in a fixed order: the current function, any enclosing functions, the module (global) level, and finally the built-ins such as print and len. If none of them holds the name, you get a NameError. The search happens when the line runs, not when the file is read. That is why a program can print several lines and then crash. For the full lookup rules see Python scope.

price = 20
try:
    print(prce * 2)
except NameError as err:
    print("NameError:", err)
    print("Missing name:", err.name)

How to read a NameError traceback

Traceback (most recent call last):
  File "main.py", line 3, in <module>
    print(totl / len(prices))
          ^^^^
NameError: name 'totl' is not defined. Did you mean: 'total'?

1. Read the last line first: it names the missing word.
2. The line above shows the file and line number, and the ^^^^ marks exactly where the name appears.
3. If you see Did you mean, Python found a similar name. That is usually your typo.
4. Ask yourself one question: "Was this name created before this line ran, and in a place this line can see?"

Cause 1: a typo or the wrong capitalisation

Python is case-sensitive, so Total, total and totl are three different names. The same goes for built-ins: it is print, not Print, and True, not true. Values copied from JSON (true, null) cause this too.

total = 99
try:
    print(Total + 1)
except NameError as err:
    print("NameError:", err)

try:
    active = true
except NameError as err:
    print("NameError:", err)

active = True
print("Fixed:", total + 1, active)

Cause 2: using a name before you assign it

Python runs top to bottom. A variable or a function must exist before the line that uses it. Calling a function above its def is the most common version of this, and so is a variable that only gets a value inside an if branch that never ran.

try:
    welcome("Asha")
except NameError as err:
    print("NameError:", err)

def welcome(name):
    return f"Welcome, {name}!"

print(welcome("Asha"))

Move the def (or the assignment) above the first use. Learn more about defining functions in Python functions and about naming values in Python variables.

Cause 3: forgetting the quotes around text

Without quotes, Python treats Asha as a name to look up instead of a piece of text. If you meant a string, wrap it in quotes.

try:
    print(Asha)
except NameError as err:
    print("NameError:", err)

print("Asha")

Cause 4: forgetting to import a module

Modules such as math or random are not available until you import them. Using math.sqrt(16) without import math gives name 'math' is not defined. Put imports at the top of the file. More in Python modules.

try:
    print(math.sqrt(16))
except NameError as err:
    print("NameError:", err)

import math
print(math.sqrt(16))

Cause 5: a variable that lives in another scope

A variable created inside a function exists only while that function runs. Code outside cannot see it. Return the value instead of hoping it leaks out.

def add_tax(price):
    total = price * 1.2
    return total

add_tax(50)
try:
    print(total)
except NameError as err:
    print("NameError:", err)

total = add_tax(50)
print(total)

Cause 6: deleting a name with del

del total removes the name completely. Any later use raises a NameError, which can surprise you when del sits in a cleanup step. Assign the name again, or avoid deleting it.

A defensive pattern: define before you branch

If a value is created only inside an if or a loop, give it a starting value first. That way the name always exists, even when the branch never runs. Reserve try/except NameError for experiments, not for normal control flow (see Python exceptions).

scores = [55, 62, 48]
best = None                      # always defined
for score in scores:
    if score > 90:
        best = score
print("Best above 90:", best)

NameError vs UnboundLocalError vs AttributeError

• NameError: the name does not exist anywhere Python looked.
• UnboundLocalError: the name exists in a function but was read before it got a value. It is a subclass of NameError.
• AttributeError: the name exists, but the object has no such attribute, like math.sqroot.

import math
print(issubclass(UnboundLocalError, NameError))
try:
    math.sqroot(4)
except AttributeError as err:
    print("AttributeError:", err)

If the line has a grammar problem instead, you get a SyntaxError, which is reported before any line runs.