Variable Scope in Python

What is scope in Python?

Scope is the part of a program where a variable name can be used. Each function call gets its own set of names, so a variable created inside a function can only be used inside it.

def make_greeting():
    message = "Hello!"
    print(message)

make_greeting()
print(message)

Hello!
Traceback (most recent call last):
  File "main.py", line 6, in <module>
    print(message)
          ^^^^^^^
NameError: name 'message' is not defined

Inside the function, message works. Outside, the name can't be seen, because it belongs to the function's own set of names, which Python calls a namespace.

What is the difference between local and global variables?

A local variable lives inside one function, and a global variable lives outside every function, at the file's top level. Every function in the file can read a global variable, with no keyword needed.

tax_rate = 0.2

def price_with_tax(price):
    return price + price * tax_rate

print(price_with_tax(100))

120.0

Parameters are local variables too. In price_with_tax(), price is local, and tax_rate is read from the global scope because the function never assigns to it.

Why doesn't an assignment inside a function change a global variable?

Assigning to a name inside a function creates a local variable, even when a global variable has the same name. The global keeps its value, and the local one disappears when the function returns.

count = 0

def reset():
    count = 10
    print("inside:", count)

reset()
print("outside:", count)

inside: 10
outside: 0

The two count variables share a name and nothing else. The rule protects you, because a function can't overwrite a global by accident when it reuses a common name such as total or i.

How do I change a global variable inside a function?

Put global and the name at the top of the function, as in global count. Assignments to that name then change the global variable instead of creating a local one.

count = 0

def increment():
    global count
    count += 1

increment()
increment()
print(count)

2

Even so, most Python code avoids global. A function that changes globals is harder to test and reuse, because its result depends on values outside it. The usual alternative is to pass the value in and return the new one.

def increment(n):
    return n + 1

count = 0
count = increment(count)
count = increment(count)
print(count)

2

This version has no hidden link to the outside, so each call shows which value goes in and where the result goes.

Why do I get UnboundLocalError in Python?

Python raises UnboundLocalError when a function reads a local variable before giving it a value. A name is local if the function assigns to it anywhere in its body, because Python decides which names are local before the function runs.

count = 0

def increment():
    count = count + 1

increment()
print(count)

Traceback (most recent call last):
  File "main.py", line 6, in <module>
    increment()
    ~~~~~~~~~^^
  File "main.py", line 4, in increment
    count = count + 1
            ^^^^^
UnboundLocalError: cannot access local variable 'count' where it is not associated with a value

The assignment makes count local for the whole function, so the count + 1 on the right reads a local variable that has no value yet. The traceback shows both steps, the call on line 6 and the failing line inside increment(). Add global count at the top of the function and the program prints 1.

Can a function change a global list without the global keyword?

Yes. Calling a method such as append() changes the list itself, and that isn't an assignment to the name.

items = []

def add(item):
    items.append(item)

add("pen")
add("book")
print(items)

['pen', 'book']

The function reads the global name items, finds the list, and changes that list in place. You need global only to make the name point to a different object, as in items = [].

Watch out for items += ["pen"] inside the function. On a list, += works like extend(), but it also assigns the result back to the name. That makes items local, so the line raises UnboundLocalError before the list changes.

What is the LEGB rule in Python?

LEGB stands for local, enclosing, global and built-in, the four scopes Python searches in that order to find a name. A name the function assigns to is local, unless a global or nonlocal line says otherwise. Python looks up any other name outward and raises NameError if no scope has it.

name = "global"

def outer():
    name = "enclosing"

    def inner():
        print(name)
        print(len(name))

    inner()

outer()

enclosing
9

A function defined inside another function is a nested function, and the outer one is its enclosing function. inner() has no local variable called name, so Python looks in outer() and finds "enclosing" before it reaches the global one.

len isn't in any of the first three scopes, so Python finds it in the built-in scope.

What does nonlocal do in Python?

nonlocal lets a nested function assign to a variable of its enclosing function. It works like global for the enclosing scope, and without it the assignment would create a new local variable.

def make_counter():
    count = 0

    def increment():
        nonlocal count
        count += 1
        return count

    return increment

counter = make_counter()
print(counter())
print(counter())

1
2

make_counter() returns the inner function without calling it, so counter now refers to increment(), and each counter() call runs it.

Normally count would disappear when make_counter() finishes, but increment() keeps it alive. A function that remembers variables from its enclosing scope like this is called a closure.

A nonlocal line at the top level of a file is a SyntaxError, because there is no enclosing function to point to.

Common mistakes with variable scope in Python

Four mistakes cause most scope bugs, and only the third one runs without an error.

• UnboundLocalError: cannot access local variable 'count' where it is not associated with a value. The function reads a name before assigning to it, and the assignment makes that name local. Add global count, or pass the value in and return it.
• NameError: name 'message' is not defined. Code outside a function used a variable created inside it. Return the value and store it where the function is called.
• Expecting an assignment to change a global. Without global, the assignment creates a local variable and the global keeps its old value, with no error at all.
• TypeError: 'list' object is not callable. A variable named list hides the built-in list(), because the global scope is searched before the built-in one, so list("abc") tries to call a list. Rename the variable, for example to items.

Run the program to see the last message. Then change list on line 1 to items, leave line 2 as it is, and the program prints ['a', 'b', 'c'].

list = [1, 2]
print(list("abc"))

Traceback (most recent call last):
  File "main.py", line 2, in <module>
    print(list("abc"))
          ~~~~^^^^^^^
TypeError: 'list' object is not callable