Python - Nonlocal Keyword

The nonlocal keyword is used inside a nested function to modify a variable that belongs to its enclosing function.

In other words, nonlocal lets an inner function change a variable of the outer function in which it is defined.

Consider a function outer() that defines a variable x and then defines another function inner() inside itself.

Inner x: 200
Outer x: 100

Inside inner(), the statement x = 200 creates a local variable of inner(). It does not touch the x of outer().

So inner() prints 200, but outer() still sees 100.

Now suppose we want the inner function to change the outer function's variable so that the outer function also sees the new value.

Plain assignment will not work because it creates a local variable. This is exactly the problem that nonlocal solves.

Inside the nested function, declare nonlocal x before assigning it:

Inner x: 200
Outer x: 200

The nonlocal x statement tells Python that x refers to the enclosing function's variable, not a local variable of inner().

Now x = 200 actually modifies the x of outer(), so both inner() and outer() print 200.

Without nonlocal	With nonlocal
Creates a local variable in the inner function.	Refers to the enclosing function's variable.
The outer variable is unchanged.	The outer variable is modified.
The outer function still sees the old value.	The outer function sees the new value.

A common use of nonlocal is a counter that the inner function increments:

Count: 1
Count: 2
Count: 3

Without nonlocal, count += 1 inside increment() would create a local variable and raise an error on first use, because a local count does not exist yet.

With nonlocal count, each call to increment() modifies the same count of counter(), so the count keeps increasing.

• nonlocal can only be used inside a nested function.
• The variable must already exist in an enclosing function.
• nonlocal cannot be used for variables at module level; use global instead.
• The name must appear in nonlocal before it is assigned in the nested function.

global	nonlocal
Refers to module-level variables.	Refers to enclosing function variables.
Can be used in any function.	Can only be used in a nested function.
The variable may not exist yet.	The variable must already exist in the enclosing scope.
Works without nesting.	Requires an enclosing function.

If no variable with the given name exists in an enclosing function, Python raises a SyntaxError.

SyntaxError: no binding for nonlocal 'x' found

Here, x does not exist in the enclosing scope, so nonlocal x is invalid. A nonlocal name must always refer to a variable that already exists in an enclosing function.