Fix: Python NameError

Python can't find the name you used. Here's how to trace it in under a minute.

Last updated: October 2026

⚡ The 30-second fix

Check three things in this order:

1. Is the name spelled exactly right? Python is case-sensitive — Name ≠ name.
2. Was it assigned before you used it?
3. If it's a module or function, did you import it?

If it's none of those, it's a scope issue — see case #3 below.

What the error means

Python executed a line that referenced a name (variable, function, class, or module) that it doesn't know about — yet. The name hasn't been defined in the current scope, or it's been defined somewhere Python can't see.

print(user_name)
# ❌ NameError: name 'user_name' is not defined

# But this works:
user_name = "Alice"
print(user_name)  # ✅ Alice

Why it happens (5 real causes)

Typo or case mismatch

Python is case-sensitive. userName and username are different names.

username = "Alice"
print(userName)   # ❌ NameError (capital N)
print(username)   # ✅

Missing import

You used a function or class that lives in a module you didn't import.

# ❌ NameError: name 'math' is not defined
print(math.sqrt(16))

# ✅ Fix
import math
print(math.sqrt(16))   # 4.0

# Or import just the function
from math import sqrt
print(sqrt(16))        # 4.0

Scope issue — variable defined in the wrong place

Variables defined inside a function are local. You can't access them outside.

def greet():
    message = "Hello"

greet()
print(message)   # ❌ NameError — message is local to greet()

# ✅ Fix: return the value
def greet():
    return "Hello"

message = greet()
print(message)   # Hello

Using a variable before assignment

Python executes top to bottom. You can't use a name that comes later in the file.

print(total)          # ❌ NameError
total = 100

# ✅ Fix: move the assignment up
total = 100
print(total)

Package not installed

You imported a third-party package that isn't installed in your environment.

# ❌ ModuleNotFoundError (a subtype of NameError)
import requests

# ✅ Fix
pip install requests

Pro tip: Check you're in the right virtual environment. which python and pip list reveal the truth.

🛡️ How to prevent it

Use an IDE with autocomplete. VS Code + Pylance flags undefined names as you type.
Enable linting. Ruff or Flake8 catch undefined names before you run.
Consistent naming. Pick snake_case (user_name) and stick with it. Never mix.
Import at the top. Keep all imports at the top of the file so they're easy to scan.
Use a virtual environment. python -m venv .venv then activate before installing packages.
Run python -m py_compile file.py before executing. It catches syntax-level issues without running the code.

Common NameError variants

Error	Most likely cause
NameError: name 'x' is not defined	Variable never assigned or typo
ModuleNotFoundError: No module named 'x'	Package not installed
ImportError: cannot import name 'x'	Function doesn't exist in module
UnboundLocalError: local variable 'x' referenced	Local variable used before assignment
AttributeError: module 'x' has no attribute 'y'	Wrong API for that module version

❓ Frequently asked questions

How do I fix Python NameError name is not defined?

Check three things in order: is the variable name spelled exactly right (Python is case-sensitive), was the variable assigned before you used it, and did you import the module or function you're calling? Most NameErrors are one of these three.

Why do I get NameError for a variable I clearly defined?

Usually a scope issue. The variable is defined inside a function or block and you're trying to use it outside. Variables defined inside functions are local to that function unless declared global or returned.

What is the difference between NameError and UnboundLocalError?

NameError means the name was never defined at all. UnboundLocalError means the name is defined elsewhere but the local variable was referenced before assignment. Both are fixed the same way — trace where the variable is defined.

Why does NameError happen on my import statement?

Either the module isn't installed (run pip install package_name), the module name is misspelled, or you're trying to import a specific function that doesn't exist in that module. Check the module's actual exports.

Does Python have a way to check if a name is defined?

Yes, but use it sparingly. The 'in' operator works on locals() and globals() dictionaries: 'x' in locals(). But using this usually indicates a code design problem — refactor instead of guarding names.