🐍 python global vs nonlocal keyword — when to use each?

A variable can be modified inside a nested function without being passed as an argument — if Python’s scope resolution rules allow it through global or nonlocal.

📑 Table of Contents

• 🧠 Scopes in Python — How Names Are Resolved
• 🌍 Global — Modifying Module-Level Names
• ⚙️ Mechanism — What Happens at Compile Time
• 📌 Practical Example — A Simple Call Counter
• ⚠️ Gotcha — Global Isn’t Always What You Want
• 🔐 Nonlocal — Accessing Enclosing Function Variables
• ⚙️ Mechanism — Cell Variables and Closure
• 📌 Practical Example — Maintaining State in a Closure
• 💡 Real-World Use Case — Retry Logic with Backoff
• 🔍 Python Global vs Nonlocal Keyword — Key Differences
• 🎯 Scope Target
• 📌 Assignment Behavior
• 🧪 Name Resolution Flow
• 🧠 Memory Implications — Closures and Reference Counting
• 🧱 When to Use Each — Best Practices
• ✅ Use global When:
• ✅ Use nonlocal When:
• 🚫 Avoid Both When:
• 🔍 Rule of Thumb
• 🟩 Final Thoughts
• ❓ Frequently Asked Questions
• Can I use both global and nonlocal in the same function?
• Why do I get UnboundLocalError when I didn’t use global or nonlocal?
• Does nonlocal work with nested classes or only functions?
• 📚 References & Further Reading

🧠 Scopes in Python — How Names Are Resolved

Python resolves names using the LEGB rule : Local → Enclosing → Global → Built-in. This governs read operations: when you reference x, Python checks these scopes in order. At function definition time, the compiler scans all assignments. If any statement assigns to a name (e.g., x = 1, x += 1), that name is classified as local to the function unless declared otherwise with global or nonlocal. This means assignment changes the scope interpretation of a name—even if the assignment comes after a read.

x = "global" def outer(): x = "enclosing" def inner(): print(x) # Which x? LEGB says: look in enclosing inner() outer() # Output: enclosing

Now consider modifying x in inner():

def outer(): x = "enclosing" def inner(): x = "local" # Creates new local x — doesn't touch outer x print(x) inner() print(x) outer()
# Output:
# local
# enclosing

The assignment in inner() binds x locally. To mutate the x in outer, you must declare intent with nonlocal.

---

🌍 Global — Modifying Module-Level Names

The global keyword binds a name to the module-level namespace (globals()), regardless of nesting depth. This enables shared state across functions in the same module—useful for debug flags, registries, or process-wide counters. The mechanism is straightforward: when the compiler sees global x, it treats all references to x as module-scoped.

⚙️ Mechanism — What Happens at Compile Time

During compilation, Python builds a symbol table for each function. A global declaration forces a name to be resolved via the current module’s **dict**, bypassing local and enclosing scopes entirely. Writes go directly to the module namespace. Reads pull from it. No cell objects are created; there’s no closure involvement.

📌 Practical Example — A Simple Call Counter

call_count = 0 def api_request(url): global call_count call_count += 1 print(f"Fetching {url} (call #{call_count})") # simulate request... def retry_request(url, retries=3): for i in range(retries): api_request(url) retry_request("https://httpbin.org/status/500")
# Output:
# Fetching https://httpbin.org/status/500 (call #1)
# Fetching https://httpbin.org/status/500 (call #2)
# Fetching https://httpbin.org/status/500 (call #3)

Without global, call_count += 1 would raise UnboundLocalError. The compound assignment implies local binding, yet the initial read fails because no local value exists yet.

⚠️ Gotcha — Global Isn’t Always What You Want

Using global couples functions to module state, reducing testability and increasing side-effect surface. It also introduces race conditions under concurrency unless external synchronization is applied.

def bad_idea(): global temp_result temp_result = "something" # Pollutes module namespace

Prefer return values or class attributes for intermediate data. Reserve global for genuine module-level state.

---

🔐 Nonlocal — Accessing Enclosing Function Variables

nonlocal allows a nested function to modify a variable in its immediate enclosing function scope. It's the only way to rebind names from outer function locals while preserving encapsulation. This is essential for stateful closures—like decorators, retries, or factory functions—where you need mutable upvars without resorting to classes.

⚙️ Mechanism — Cell Variables and Closure

When an inner function references a variable from an outer function, Python wraps that variable in a cell object (cell_contents). Multiple nested functions can share access to the same cell. nonlocal instructs the compiler to bind assignments to the existing cell in the nearest enclosing scope. This creates a true closure: the outer variable persists beyond the lifetime of the outer function, as long as references exist.

📌 Practical Example — Maintaining State in a Closure

This pattern is common in functional utilities:

def make_counter(): count = 0 # Local to make_counter def increment(): nonlocal count count += 1 return count return increment counter_a = make_counter()
counter_b = make_counter() print(counter_a()) # 1
print(counter_a()) # 2
print(counter_b()) # 1 — independent state

Without nonlocal, count += 1 would trigger UnboundLocalError. The variable is visible due to LEGB, but assignment creates a local by default, shadowing the closure binding.

💡 Real-World Use Case — Retry Logic with Backoff

import time def exponential_retry(max_retries=3): attempt = 0 delay = 1 def should_retry(func): nonlocal attempt, delay while attempt < max_retries: try: return func() except Exception as e: attempt += 1 print(f"Attempt {attempt} failed: {e}, retrying in {delay}s") time.sleep(delay) delay *= 2 # Exponential backoff raise RuntimeError("Max retries exceeded") return should_retry # Usage
network_call = exponential_retry(max_retries=3)(lambda: requests.get("https://httpbin.org/status/500"))

nonlocal enables stateful retry logic without global variables or class instantiation. The closure captures attempt and delay in cells, allowing mutation across invocations.

Use global to modify module state, nonlocal to modify closure state — never use either for temporary values.

---

🔍 Python Global vs Nonlocal Keyword — Key Differences

The python global vs nonlocal keyword difference lies in the target scope and resolution path.

🎯 Scope Target

- global: binds to the module-level namespace (globals()).

- nonlocal: binds to the nearest enclosing function’s local scope—must be a function, not module or class scope. Using nonlocal on a global name raises SyntaxError:

x = "global" def outer(): def inner(): nonlocal x # SyntaxError: no binding for nonlocal 'x' found

Because x exists in the global scope, not a function enclosure. The compiler finds no matching name in any enclosing function scope, so the declaration is invalid.

📌 Assignment Behavior

Both keywords allow mutation of outer scopes otherwise accessible only for reading. Only nonlocal enables closure mutation , supporting functional patterns like memoization, configuration factories, or stateful decorators.

🧪 Name Resolution Flow

For x = 5 in a function: 1. Compiler checks for global x → binds to module scope.

2. Else, checks for nonlocal x → binds to enclosing function’s cell.

3. Else, creates or overwrites x in local scope. For reading x: 1. Runtime searches: Local → Enclosing → Global → Built-in (LEGB).

2. nonlocal does not alter read behavior—only assignment binding. This explains why reads are permitted freely, but writes require explicit scope declaration.

def outer(): x = "enclosing" def inner(): print(x) # OK — read allowed # x = "local" # Uncommenting breaks the read above inner()

Once x is assigned, it becomes local. The preceding print(x) tries to access a local x before it's defined—hence the UnboundLocalError if the assignment were active.

🧠 Memory Implications — Closures and Reference Counting

Variables captured by nonlocal are stored in cell objects that remain alive as long as any referencing closure exists. This prevents the outer function’s frame from being garbage-collected prematurely. In long-running processes with many dynamically generated closures—such as async task factories or middleware chains—this can accumulate memory. The effect is expected and usually negligible, but becomes measurable when thousands of closures retain references to large outer variables. Consider limiting captured data size or using weak references when appropriate.

---

🧱 When to Use Each — Best Practices

Choice between global and nonlocal should reflect intent and isolation needs.

✅ Use global When:

- Maintaining process-wide state like debug flags, logging levels, or feature toggles.

- Writing scripts where module scope is the natural state container.

- Implementing registries or singletons (with caution—prefer classes). Avoid global in reusable libraries; it undermines composability and makes unit testing harder.

✅ Use nonlocal When:

- Building stateful closures: counters, accumulators, retry trackers.

- Writing decorators that need internal state.

- Returning callable factories with private mutable state. It's safer than global because state is encapsulated within function closures, not exposed at module level.

🚫 Avoid Both When:

- A class would make state and behavior clearer.

- Return values and reassignment suffice.

- Temporaries are involved—use locals. Classes offer better extensibility and debugging affordance:

class Counter: def __init__(self): self.count = 0 def increment(self): self.count += 1 return self.count

This is more explicit than a closure with nonlocal, especially when additional methods or attributes are needed.

🔍 Rule of Thumb

If you're debating global or nonlocal, ask whether a class or generator would better express the intent. They’re specialized tools—not substitutes for proper data modeling.

---

🟩 Final Thoughts

The global and nonlocal keywords are not conveniences—they are explicit mechanisms for controlling Python’s scoping and closure behavior. Understanding the python global vs nonlocal keyword distinction means understanding how Python binds names at compile time and manages variable lifetime through cell objects. Assignment in Python is not neutral—it defines scope. Without global or nonlocal, any assignment traps the name in the local scope, even if you intended to modify an outer binding. In modern Python, prefer immutability, clear interfaces, and encapsulated objects. Use nonlocal sparingly for lightweight functional patterns. Use global only when module-level state is intentional and documented. Most state management problems are better served by classes, generators, or context managers—but when you need a minimal, stateful closure, knowing how nonlocal works is essential.

❓ Frequently Asked Questions

Can I use both global and nonlocal in the same function?

Yes, but only for different variables. You can declare one name as global and another as nonlocal in the same function. Applying both to the same name is a logical contradiction and results in a SyntaxError. (Also read: 🐍 python pip vs pipenv vs poetry — which one should you actually use?)

Why do I get UnboundLocalError when I didn’t use global or nonlocal?

Because Python sees an assignment (like x = x + 1) and marks x as local to the function. Any read of x before the assignment then refers to a local variable that hasn’t been initialized. Use global or nonlocal to bind to an outer scope instead.

Does nonlocal work with nested classes or only functions?

No, nonlocal only applies to nested functions. Classes—even those defined inside functions—do not participate in the closure mechanism. Their scope is evaluated independently, and they cannot access enclosing function variables via nonlocal.

📚 References & Further Reading

• Python scoping rules — official documentation on LEGB and namespace resolution: docs.python.org
• Closures and free variables — how cell objects work in nested functions: docs.python.org
• Global and nonlocal statements — syntax and semantics: docs.python.org