Python UnboundLocalError — What It Means & How to Fix It

What Does This Error Mean?

An UnboundLocalError means you used a variable inside a function before giving it a value in that same function. Python sees that the variable is assigned somewhere inside the function and decides it is a local variable — but when Python tries to read it before that assignment runs, it has no value yet. The fix is to either assign the variable before you use it, or tell Python to use the version from outside the function.

Affected Models

Python 3.12
Python 3.11
Python 3.10
Python 3.9
Python 3.8

Common Causes

Using a variable inside a function before the line that assigns it has run
A variable exists outside a function (global scope), and the function also assigns to it — Python treats it as local everywhere inside that function
An if/else block assigns the variable only in one branch, but the other branch reads it first
Using += or -= on a variable that was never initialized in the local scope
Confusing a global variable with a local one of the same name

How to Fix It

Read the error message. It tells you the function name and the variable name that has no value yet.

Example: 'UnboundLocalError: local variable "count" referenced before assignment' — look at every use of 'count' inside that function.
Find where the variable is first assigned inside the function. Make sure that assignment runs BEFORE the line that reads the variable.

If the assignment is inside an if block, it may not always run. Add a default value at the top of the function: count = 0.
If the variable lives outside the function (global scope) and you want to use it inside, add 'global variable_name' at the top of the function.

Example: add 'global count' as the first line of the function. This tells Python you mean the outside variable, not a new local one.
If you only need to read the global variable (not change it), just remove the assignment from inside the function. Python will automatically read the outer one.

You only need 'global' if you want to assign a new value to the outer variable from inside the function.
For += or similar operators, make sure the variable is initialized first. Replace the += with a full assignment if the variable might not exist yet.

Instead of 'count += 1', use 'count = count + 1 if count is defined, or just set count = 1' at the start of the function.
Run your code again and confirm the error is gone. Check any other functions that use the same variable name.

Each function has its own local scope. A variable in one function is completely separate from a variable with the same name in another function.

When to Call a Professional

UnboundLocalError is always something you can fix yourself by reading the error message and tracing the variable. If the logic is complex and you cannot see why the variable is unbound, paste the relevant function into Stack Overflow or ask a senior developer to review the variable scope. The Python docs on 'scope and namespaces' are also a clear reference.

Frequently Asked Questions

Why does Python cause this error just because I also assign the variable later in the function?

Python scans the entire function before running it. If it sees any assignment to a variable name anywhere in the function, it marks that name as local for the whole function. So even if the assignment is on line 20 and you read the variable on line 5, Python already decided it is local — and it has no value yet on line 5.

My code worked fine yesterday and now gives UnboundLocalError — what changed?

The most common cause is that you added an assignment to a variable inside the function since yesterday. Even adding one line like 'x = something' at the bottom of a function changes how Python treats 'x' throughout the entire function. Check your recent changes for any new assignments to that variable name.

Is it bad practice to use global variables to fix this?

Using 'global' works but is generally considered bad practice for large programs because it makes code harder to understand and test. A better approach is to pass the variable as a parameter to the function and return the new value. For small scripts, 'global' is fine.