global and nonlocal Keywords in Python

Both global and nonlocal tell Python that a name inside a function refers to a binding that lives further out. The difference is how far out they reach.

counter = 0


def bump():
    global counter        # this name lives at module level
    counter += 1


bump()
bump()
print(counter)          # 2


def outer():
    total = 0

    def inner():
        nonlocal total     # this name lives in outer()'s scope
        total += 10
        return total

    inner()
    return total


print(outer())           # 10

The global keyword reaches the module scope, which is the outermost namespace in the program. The bump function can read and rebind the module-level counter, and the change is visible to everybody else in the file.

The nonlocal keyword reaches the nearest enclosing function scope and it skips the module entirely. Inside outer, the name total is a local of outer, so inner can read and rebind it with nonlocal, and outer sees the new value of 10 afterwards. Without the nonlocal statement, the line total += 10 inside inner would create a brand new local named total inside inner, and outer would still see 0 when it returns.

Two rules catch people out here. nonlocal needs the name to already exist in an enclosing function scope. There is no such thing as a nonlocal that creates a module-level name, and using nonlocal for a name that does not exist yet raises a SyntaxError before your program even starts. And nonlocal can only skip function scopes. It cannot reach a name in a class body, because class bodies are not part of the chain of enclosing scopes that nonlocal searches.

The safe pattern is the same one that you use for global. Rebind a name rather than mutating it wherever you can, and prefer returning a value over changing one in place.

The global keyword binds a name to the module scope, which is the top of the chain of scopes. The nonlocal keyword binds a name to the nearest enclosing function scope, which means the closest function that is not the one currently running. You need both of them because an assignment inside a function creates a local name by default, so without one of these keywords the assignment would never reach the outer binding at all.

The difference between them shows up in the scope chain. Imagine a module-level variable that is read inside a function that is nested two levels deep. With global, the name resolves at module level. With nonlocal, the search stops at the nearest enclosing function, and if no enclosing function has that name then Python raises a SyntaxError at compile time. A nonlocal also cannot reach a class-body attribute, because class scopes are not part of the chain that nonlocal searches.

The reason it is usually a bad idea is about hidden coupling. A function that rebinds a global has a dependency that you cannot see in its signature, so a caller cannot tell what the function touches, and a test cannot control it without setting up module state first. The behaviour of the function also depends on the order of the calls, which makes the program harder to reason about, and it makes concurrency riskier, because two threads that change the same global both need locking.

The other side of the argument is that some state really is global. A configuration value, a pool of connections, or a cache is a reasonable thing to share. The distinction to draw in an interview is between a module-level object that you share on purpose, and a bare global variable that a function quietly rewrites. The first one is a design decision. The second one is usually an accident that is waiting to happen.