Python nonlocal keyword: scope and closures
Learn how Python's nonlocal keyword works, when to use it in nested functions, and how it differs from global and local scope.

The nonlocal keyword in Python lets a nested function rebind a variable that exists in an enclosing function's scope. Without it, assignment inside the nested function creates a new local variable instead of updating the outer one. This distinction is easy to miss and produces subtle bugs.
What nonlocal actually changes
In Python, assignment to a name inside a function makes that name local to the function by default. When a function is nested inside another, the inner function's local scope is separate from the outer function's scope. The nonlocal declaration tells the interpreter that a particular name refers to a variable bound in the nearest enclosing function scope, excluding globals. It does not create a new variable; it rebinds an existing one.
def outer():
count = 0
def inner():
nonlocal count
count += 1
return count
return innerHere count is defined in outer. The inner function uses nonlocal count so that count += 1 updates the outer variable rather than attempting to create a local count. Without the declaration, Python would raise UnboundLocalError because the assignment makes count local to inner, and it is read before being assigned.
How nonlocal differs from global
The global keyword rebinds a module-level name. nonlocal works only within nested functions and binds to a name in an enclosing function's scope, not the module scope. The two keywords are not interchangeable.
x = 10
def outer():
x = 5
def inner():
global x # refers to module-level x
x += 1
inner()
print(x) # 5, unchanged
print(x) # 11With nonlocal, the same example updates the x in outer:
def outer():
x = 5
def inner():
nonlocal x
x += 1
inner()
print(x) # 6Use global when you intend to modify a module-level binding. Use nonlocal when you need to modify a binding in an enclosing function. Using global and nonlocal for different names in the same nested function is allowed but rarely necessary.
Practical use: closures with mutable state
The most common use of nonlocal is building closures that retain state between calls. A closure is a function that captures variables from its enclosing scope. The nonlocal keyword makes that captured state writable.
def make_counter(start=0):
value = start
def increment(step=1):
nonlocal value
value += step
return value
return increment
counter = make_counter(10)
print(counter()) # 11
print(counter(5)) # 16This pattern is useful for stateful callbacks, lazy initialization, or memoization. The state lives in the closure and is isolated from other instances of the same factory function.
Common mistake: forgetting nonlocal
If you assign to a variable inside a nested function without declaring it nonlocal, Python treats it as a new local variable. The outer variable remains unchanged; if the code reads the local variable before assigning it, Python raises UnboundLocalError.
def outer():
items = []
def add(item):
items = items + [item] # UnboundLocalError: items referenced before assignment
return items
return addThe error occurs because items is local due to the assignment, and the right-hand side reads it before it has a value. Using nonlocal items fixes this. Alternatively, avoid rebinding by mutating the list in place:
def outer():
items = []
def add(item):
items.append(item) # no nonlocal needed, mutation only
return items
return addMutation does not require nonlocal because you are not reassigning the name items. This distinction is a frequent source of confusion.
When to avoid nonlocal
nonlocal adds a hidden dependency on the enclosing function's state. This can make the code harder to reason about, especially when the closure is long or the outer function has many variables. In many cases, a small class or a mutable container is clearer.
class Counter:
def __init__(self, start=0):
self.value = start
def increment(self, step=1):
self.value += step
return self.valueA class makes the state explicit and avoids the scope magic. Use nonlocal when the state is trivial and the closure is short. For more complex state, prefer a class.
Another alternative is to store state in a mutable object like a list or dictionary. This avoids nonlocal entirely but obscures intent. The nonlocal version is often more readable because it names the variable directly.
Runtime behavior and debugging
nonlocal is resolved by Python's scoping rules at compile time. The nested function captures the variable from the enclosing scope, and the closure holds a reference to that cell for its lifetime.
Debugging closures that use nonlocal can be tricky because the state is not visible in the local frame of the inner function. Tools like inspect can help, but a simpler approach is to add logging or to temporarily return the state for inspection. The closure's __closure__ attribute contains the captured cell objects, and you can read their cell_contents.
counter = make_counter(10)
print(counter.__closure__[0].cell_contents) # 10This is useful for understanding what the closure holds, but it is not something you would use in production code.
Maintainability tradeoffs
Using nonlocal in a deeply nested structure can make the data flow implicit. A reader must trace which enclosing function defines the variable and where it is modified. This is acceptable for a two-level nesting, but beyond that, the code becomes difficult to follow.
A more maintainable pattern is to keep the closure small and the state minimal. If the outer function has many variables that need to be modified from inner functions, consider refactoring into a class. The class makes the state a first-class attribute, and methods can modify it without any scope declaration.
Another consideration is that nonlocal only works inside a nested function. You cannot use it at module level or in a class body. Attempting to do so raises a SyntaxError. This constraint is by design: the keyword exists specifically for enclosing function scopes.
When you need to share state across multiple nested functions, each one must declare nonlocal for the same variable. This repetition is fine for one or two functions, but it can become noisy. A class with shared attributes often reads better in that situation.
Finally, be aware that nonlocal does not affect the variable's lifetime. The variable lives as long as the closure does. If the outer function returns and the closure is still referenced, the captured variable persists in memory. This is the same behavior as any closure, and it is usually what you want for stateful callbacks.
In summary, the nonlocal keyword is a precise tool for rebinding variables in enclosing scopes. Use it when you need a closure with writable state and the nesting is shallow. For deeper nesting or more complex state, a class is often a clearer choice. Understanding the distinction between rebinding and mutation, and knowing when not to use nonlocal, is more valuable than memorizing the syntax.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.