Python Local vs Nonlocal Variable: Scope Explained
Understand how Python resolves local and nonlocal variables in nested functions, when to use the nonlocal keyword, and how it differs from global.

Understanding Python's local and nonlocal variable rules is essential for working with nested functions. When you assign a variable inside a function, it is local to that function by default. To modify a variable from an enclosing function, you must declare it with the nonlocal keyword. This article explains how Python resolves local and nonlocal variables, when nonlocal is required, and how it differs from global.
The Core Difference Between Local and Nonlocal Variables
In Python, a variable is considered local to a function if it is assigned anywhere in that function's body. This rule applies even if the assignment appears after a reference to the variable. For example:
def outer():
print(x) # UnboundLocalError
x = 10Python determines at compile time that x is local to outer, so the print statement tries to access a local variable that hasn't been assigned yet. This behavior is the foundation of the local vs nonlocal distinction.
A nonlocal variable, on the other hand, is a variable defined in an enclosing function but not in the global scope. It exists in the scope between the innermost function and the module level. The nonlocal keyword allows an inner function to bind to that variable and modify it.
How Python Resolves Variable Names in Nested Functions
When you nest functions, Python uses the LEGB rule to resolve names: Local, Enclosing, Global, Built-in. For a variable referenced inside an inner function, Python first checks the local scope of that function, then the enclosing scopes (from innermost outward), then the global scope, and finally the built-in scope.
Consider this example:
def outer():
message = "hello"
def inner():
print(message) # reads from enclosing scope
inner()Here, inner can read message because it is found in the enclosing scope. This is a closure: the inner function captures the variable from the outer function. However, if inner tries to assign to message, it creates a new local variable unless nonlocal is used.
Using nonlocal to Modify an Enclosing Scope
The nonlocal statement tells Python that a variable refers to a binding in the nearest enclosing function scope. The declaration must appear before any use of that name in the inner function. Here is a minimal example using a counter:
def make_counter():
count = 0
def increment():
nonlocal count
count += 1
return count
return increment
counter = make_counter()
print(counter()) # 1
print(counter()) # 2Without nonlocal, count would be treated as a local variable inside increment, so count += 1 would raise UnboundLocalError because it reads count before it has been assigned. The nonlocal keyword makes count refer to the count defined in make_counter, allowing the closure to mutate it across calls.
The same mechanism works for any nested function that needs to update a value from an enclosing scope. It is not limited to counters; it applies to accumulators, stateful decorators, and any pattern where an inner function must modify state that belongs to an outer function.
nonlocal vs global: When Each Applies
The global keyword modifies a variable in the module-level scope, while nonlocal modifies a variable in the nearest enclosing function scope. The two are not interchangeable. nonlocal cannot refer to a global variable, and global cannot refer to a variable in an enclosing function.
Here is a comparison:
| Keyword | Scope it targets | Example usage |
|---|---|---|
global | Module-level | global x in a function to modify a module variable |
nonlocal | Enclosing function | nonlocal x in a nested function to modify an outer function's variable |
A common mistake is using global inside a nested function when the intent is to modify a variable from the outer function. That changes the module-level variable, not the enclosing one. Conversely, using nonlocal at the module level is a syntax error because there is no enclosing function scope.
Common Mistakes and Pitfalls
One frequent error is forgetting to declare nonlocal before assigning to a variable that exists in an enclosing scope. This leads to UnboundLocalError or, worse, silently creating a new local variable that shadows the outer one.
Another pitfall is using nonlocal on a variable that does not exist in any enclosing function. Python raises SyntaxError: no binding for nonlocal 'x' found. The variable must be defined in an outer function, not just in the global scope.
Also, nonlocal only works inside nested functions. If you attempt to use it in a function that is not nested, you get a syntax error. This is a common source of confusion when refactoring code from a nested structure to a flat one.
Finally, be aware that nonlocal binds to the variable in the nearest enclosing scope, not necessarily the outermost one. If there are multiple levels of nesting, nonlocal in the innermost function refers to the first enclosing function that defines the variable.
Practical Example: Stateful Closure with nonlocal
A realistic use case is a function that builds a reusable stateful callback. For instance, a rate limiter that tracks the last call time:
def rate_limiter(interval):
last_call = 0
def allow():
nonlocal last_call
import time
now = time.time()
if now - last_call >= interval:
last_call = now
return True
return False
return allow
limit = rate_limiter(2)
print(limit()) # True
print(limit()) # FalseHere, last_call is updated inside allow using nonlocal. Without it, the closure would not retain the updated value between calls, and the rate limiter would not work as intended.
This pattern is common in decorators that need to maintain per-function state, such as memoization caches or call counters. The nonlocal keyword makes the state explicit and avoids relying on mutable defaults or global variables.
Performance and Maintainability Considerations
The runtime cost of nonlocal is generally small because the name binding is resolved when the function is compiled rather than through a dynamic lookup. The exact cost can vary by Python implementation, so do not optimize based on this distinction unless profiling shows a hotspot.
From a maintainability perspective, nonlocal can make code harder to reason about because it creates hidden state that persists across calls. This is intentional in closures, but it can surprise developers who expect functions to be stateless. When you use nonlocal, document the state clearly and keep the closure small. If the state becomes complex, consider using a class instead.
A class with instance attributes often provides clearer state management than a closure with multiple nonlocal variables. For example, a counter can be implemented as:
class Counter:
def __init__(self):
self.count = 0
def increment(self):
self.count += 1
return self.countThis is more verbose but makes the state explicit and easier to test. The choice between a closure with nonlocal and a class depends on the complexity of the state and the need for additional methods.
When to Avoid nonlocal
Avoid nonlocal when the state can be passed as an argument and returned as a result. Functional programming styles that avoid mutable state are often easier to debug and test. For example, instead of a closure that increments a counter, you can write a pure function that takes a counter and returns a new one.
Also, avoid nonlocal in recursive functions that need to accumulate results across calls. In such cases, passing the accumulator as an argument is clearer and avoids hidden state. The nonlocal keyword is best suited for situations where you need to create a stateful function on the fly, such as a decorator or a callback that must remember previous inputs.
Finally, be cautious when using nonlocal in multithreaded or asynchronous code. The state is shared across calls, and without proper synchronization, concurrent modifications can lead to race conditions. If you need thread safety, use a lock or consider a different design, such as a class with an explicit lock.
Understanding the distinction between local and nonlocal variables is essential for writing correct nested functions in Python. The nonlocal keyword gives you a controlled way to modify enclosing state, but it should be used deliberately and with a clear understanding of the scope rules involved.
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.