How can a name be “unbound” in Python? What code can cause an `UnboundLocalError`?

by

You can refer to a name without having assigned to it:

>>> foobar
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'foobar' is not defined

Here foobar is being referred to, but was never assigned to. This raises a NameError because the name was never bound.

More subtly, here assignment is not happening because the line that does is never run:

>>> def foo():
...     if False:
...         spam = 'eggs'
...     print(spam)
... 
>>> foo()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 4, in foo
UnboundLocalError: local variable 'spam' referenced before assignment

Because spam = 'eggs' is never executed, print(spam) raises an UnboundLocalError.

Note that nowhere in Python is a name ever declared. You bind or don’t bind, declaration is not part of the language.

Instead, binding is used to determine the scope of a name; binding operations include assignment, names used for a for loop, function parameters, import statements, name to hold a caught exception in an except clause, and the name for a context manager in a with statement.

If a name is bound in a scope (such as in a function) then it is a local name, unless you use a global statement (or a nonlocal statement in Python 3) to explicitly mark the name as a global (or a closure) instead.

So the following is an error:

>>> foo = None
>>> def bar():
...     if False:
...         foo = 'spam'
...     print(foo)
... 
>>> bar()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 4, in bar
UnboundLocalError: local variable 'foo' referenced before assignment

because foo is being bound somewhere in the bar function scope. But if you mark foo as a global, the function works:

>>> foo = None
>>> def bar():
...     global foo
...     if False:
...         foo = 'spam'
...     print(foo)
... 
>>> bar()
None

because now the Python compiler knows you wanted foo to be a global instead.

This is all documented in the Naming and Binding section of the Python reference documentation.

More Related Contents:

  1. What does if __name__ == "__main__": do?
  2. How to add numbers inside a variable? [closed]
  3. How to use variables from a function in a different function
  4. How can you dynamically create variables? [duplicate]
  5. What is the purpose of the single underscore “_” variable in Python?
  6. How do I put a variable’s value inside a string?
  7. Getting the name of a variable as a string
  8. How to use a variable inside a regular expression?
  9. How do I check if a variable exists?
  10. Are Python variables pointers? Or else, what are they?
  11. Checking multiple values for a variable [duplicate]
  12. How to get the original variable name of variable passed to a function
  13. Importing variables from another file?
  14. How would I access variables from one class to another?
  15. Variable assignment and modification (in python) [duplicate]
  16. How can I print variable and string on same line in Python?
  17. What is the naming convention in Python for variable and function?
  18. Dynamic variable in Python [duplicate]
  19. Convert Variable Name to String?
  20. If two variables point to the same object, why doesn’t reassigning one variable affect the other?
  21. How to create module-wide variables in Python? [duplicate]
  22. How do I save and restore multiple variables in python?
  23. Setting variables with exec inside a function
  24. pyodbc – How to perform a select statement using a variable for a parameter
  25. Best way to retrieve variable values from a text file?
  26. How references to variables are resolved in Python [duplicate]
  27. More elegant way of declaring multiple variables at the same time
  28. Creating multiple variables [duplicate]
  29. How to modify the local namespace in python
  30. Using a loop in Python to name variables [duplicate]

Leave a Comment