What Are the LEGB Scope Rules?

LEGB is the order that Python follows when it meets a name in your code. It stands for Local, Enclosing, Global, and Built-in. Python looks in those four places one after the other, and the first place that has a matching name is the one that wins.

name = 'global'


def outer():
    name = 'enclosing'

    def middle():
        name = 'local'
        return name              # L - found in the local scope

    def read_enclosing():
        return name              # E - not local, found one level up

    return middle(), read_enclosing(), name


print(outer())                  # ('local', 'enclosing', 'enclosing')
print(name)                    # global
print(len('abc'))              # B - len comes from the built-in scope

The middle function has its own name, so Python finds it in the local scope. The read_enclosing function has no local name, so the search moves up one level and finds the name in the enclosing function. Inside outer itself, the same name resolves to enclosing, because Python checks the enclosing scope before it checks the global one. At module level the name is global, and len is found in the built-in scope because nothing else in the program defines it.

The rule that matters most is this one: a function never reads a variable from the scope of whoever called it. Python works out names when it compiles the code, using the static structure of the program. That is why a function defined inside another function can see the outer function's variables, and why a function defined at module level cannot see the local variables of a caller, even when the caller is another function.

Reading a global from inside a function is perfectly normal, and it needs no special keyword. Writing to a name is the different case. Assigning to a name inside a function creates a local variable by default, which is exactly why you need the global or nonlocal keywords when you want to rebind a name that lives further out.

Reading a global from inside a function works with no extra syntax at all. Assigning to that same name inside the function does not touch the global at all. It creates a new local variable that hides the global for the rest of that function.

count = 0


def show():
    print(count)      # reads the global - 0


def shadow():
    count = 5         # creates a LOCAL count
    print(count)      # 5


show()                # 0
shadow()              # 5
print(count)          # 0 - the global was never touched

That last line is the one that catches people out. Inside the shadow function, the assignment makes count a local name for the whole function body, so the print statement reads the local value. The module-level count is never touched, and the global lookup only happens inside show, which never assigns to it.

There is one subtle consequence that is worth naming. Because Python decides at compile time whether a name is local, a function that reads a global before it assigns to it raises an UnboundLocalError instead of reading the global and then creating a local. Reading a name and then assigning to it in the same function means that the earlier read is looking for a local that does not exist yet.

The practical rule is to avoid shadowing names in the first place. If a local has the same name as a module-level constant, or as a parameter of another function, then the reader has to work out which one is in play. Prefixing a name with an underscore, or simply choosing a more specific name, removes the ambiguity without changing any behaviour at all.

Functions get their own scope so that they stay predictable and easy to test on their own. If a function could see and change the variables of whoever called it, then what the function meant would depend entirely on where it was called from, and there would be no way to reason about a function without running the whole program around it. Local scope is what makes functions easy to put together, and it is what lets you test a single function in isolation.

The global keyword exists for the cases where a function really does have to update state that belongs to the module. A counter that the rest of the program must see, a configuration value that is set when the program starts, or a registry that an import fills in. The problem it introduces is that the function now has a hidden dependency on state that it does not take as a parameter and does not return. Two things follow from that. The function becomes harder to test, because the test has to set up the global correctly first. And it becomes harder to reason about, because the value of the global depends on the order in which the functions were called.

There is also a sharp edge to watch for, which is UnboundLocalError. If a function declares a name global and also assigns to it somewhere, then the global declaration applies to the whole function. Any read before the assignment reads the global, and the same name cannot also be local. Mixing the two ideas inside one function is a bug waiting to happen.

The best advice to give in an interview is to pass state in as arguments and return new state out. Reserve the global keyword for the small number of cases where a shared module-level value really is the right design. If a function needs to update a counter, then take the counter as an argument or return the new value.