UnboundLocalError vs NameError Explained

UnboundLocalError and NameError can look very similar at first.

Both happen when Python has a problem with a variable name. But they do not mean the same thing.

This page helps you quickly tell the difference:

  • NameError means Python cannot find the name at all
  • UnboundLocalError means Python treats the name as a local variable, but you used it before it got a value

If you are new to Python variables and scope, this difference can be confusing. The examples below show exactly what each error means and how to fix it.

Quick fix

x = 10

def show_value():
    # If you only want to read x, do not assign to x in this function
    print(x)

show_value()

If Python says NameError, the variable name usually does not exist in the current scope.

If Python says UnboundLocalError, Python thinks the name is local in the function, but you used it before assigning a value.

What this page helps you fix

  • Understand why UnboundLocalError and NameError look similar
  • Learn the key difference between "not defined" and "local before assignment"
  • Use simple rules to identify the right fix
  • See short examples for both errors

What NameError means

NameError happens when Python cannot find a variable or function name.

In simple terms, Python looks for the name and does not find it where it expects to.

Common causes:

  • A typo in a variable name
  • Using a variable before creating it
  • Calling a function that was never defined
  • Forgetting to import something before using it

If you need a full guide, see NameError in Python: causes and fixes.

What UnboundLocalError means

UnboundLocalError is a more specific scope-related error.

It usually happens inside a function.

Python decides a name is local if you assign to it anywhere in that function. If you try to read that name before the assignment line runs, Python raises UnboundLocalError.

This often surprises beginners when a global variable has the same name.

If you want more background first, see Python variables explained for beginners and Python functions explained.

Main difference in one sentence

  • NameError: Python cannot find the name
  • UnboundLocalError: Python found the name as a local variable, but it has no value yet

Example that causes NameError

Here is a simple example:

print(user_name)

This fails because user_name was never created.

You would get an error like this:

NameError: name 'user_name' is not defined

Python checks for user_name and cannot find it.

Another common example is calling a function that does not exist:

say_hello()

If say_hello was never defined or imported, Python raises NameError.

Example that causes UnboundLocalError

This example uses a global variable:

count = 10

def show_count():
    print(count)
    count = 20

show_count()

This raises:

UnboundLocalError: local variable 'count' referenced before assignment

Why?

Because Python sees count = 20 inside the function. That makes count a local variable for the whole function.

So this line:

print(count)

tries to read the local count before it has been assigned a value.

Even though there is a global count, Python does not use it here.

A simple way to think about it

Inside a function:

  • If you only read a variable, Python may use an outer value
  • If you assign to that variable in the function, Python treats it as local
  • If you read it before assigning it, you get UnboundLocalError

For a full fix guide, see UnboundLocalError: local variable referenced before assignment.

How to fix NameError

Try these checks:

  • Check for spelling mistakes
  • Make sure the variable is assigned before you use it
  • Make sure the function or module was defined or imported
  • Check whether the name is inside the correct scope
  • Use print() to confirm what exists before the failing line

Example: fix a typo

Bad code:

message = "Hello"
print(mesage)

Fixed code:

message = "Hello"
print(message)

Example: assign before use

Bad code:

print(total)
total = 5

Fixed code:

total = 5
print(total)

Example: import before use

Bad code:

print(math.sqrt(16))

Fixed code:

import math

print(math.sqrt(16))

If imports are confusing, read how import works in Python.

How to fix UnboundLocalError

Good fixes usually include one of these:

  • Assign the variable before reading it in the function
  • Use a different local variable name
  • Pass the value into the function as an argument
  • Return a new value instead of modifying outer state
  • Use global or nonlocal only when you truly need shared state

Fix 1: pass the value into the function

Bad code:

count = 10

def update_count():
    print(count)
    count = count + 1

update_count()

Better code:

def update_count(count):
    print(count)
    count = count + 1
    return count

count = 10
count = update_count(count)
print(count)

Expected output:

10
11

This is often the best beginner-friendly solution.

Fix 2: use a different local variable name

count = 10

def show_new_count():
    new_count = count + 1
    print(new_count)

show_new_count()

Expected output:

11

Here, count is read from outside the function, and new_count is local.

Fix 3: assign before reading the local variable

def show_count():
    count = 20
    print(count)

show_count()

Expected output:

20

This works because the local variable gets its value before it is used.

When global and nonlocal are involved

Sometimes global and nonlocal are part of the fix.

  • global tells Python to use a module-level variable
  • nonlocal tells Python to use a variable from an outer function
  • These can fix some UnboundLocalError cases
  • Beginners should usually prefer arguments and return values when possible

Example with global

count = 10

def increase():
    global count
    count = count + 1
    print(count)

increase()

Expected output:

11

Because of global count, Python uses the module-level variable.

Example with nonlocal

def outer():
    count = 10

    def inner():
        nonlocal count
        count = count + 1
        print(count)

    inner()

outer()

Expected output:

11

Use these keywords carefully. They can work, but they can also make code harder to follow.

Quick debugging checklist

When you see one of these errors, check this list:

  • Read the exact error name carefully
  • Check whether the problem line is inside a function
  • Look for assignments to the same variable later in that function
  • Check whether the variable was ever created
  • Print values before the failing line if needed
  • Rename variables to avoid confusing shadowing

Helpful debugging commands:

print(variable_name)
print(locals())
print(globals().keys())
type(variable_name)
help('global')
help('nonlocal')

If you want a broader step-by-step process, see how to debug Python code.

Common mistakes

These are the most common reasons beginners see NameError or UnboundLocalError:

  • Misspelled variable or function name
  • Using a variable before assigning a value
  • Assigning to a variable inside a function after reading it
  • Confusing global and local variables
  • Forgetting to import a name before using it
  • Reusing the same variable name in nested scopes

FAQ

Is UnboundLocalError the same as NameError?

No. UnboundLocalError is a more specific scope-related error. NameError means the name cannot be found at all.

Why do I get UnboundLocalError even though the variable exists outside the function?

Because assigning to that name inside the function makes Python treat it as a local variable for the whole function.

Should I use global to fix UnboundLocalError?

Sometimes, but beginners should usually pass values into functions and return results instead.

Can NameError happen with function names too?

Yes. If you call a function that was not defined or imported, Python raises NameError.

Can a typo cause both errors?

A typo usually causes NameError. UnboundLocalError is more often caused by scope and assignment inside a function.

See also