Python Scope

Scope decides where a name can be seen. A variable created inside a function exists only inside that function, while a variable created at the top of a file can be read everywhere. Understanding scope explains several confusing errors.

Local scope

A variable assigned inside a function is local: it is created when the function runs and disappears when it returns.

def make_report():    title = "Daily report"     # local    print(title) make_report()print(title)

Daily report
Traceback (most recent call last):
  File "main.py", line 6, in <module>
    print(title)
          ^^^^^
NameError: name 'title' is not defined. Did you mean: 'tuple'?

Global scope

A variable assigned at the top level of a file is global. Functions can read it.

BASE_URL = "https://sqatools.in" def page_url(path):    return BASE_URL + path      # reading a global is fine print(page_url("/python-tutorials/"))

https://sqatools.in/python-tutorials/

Same name, different variables

Assigning inside a function creates a new local variable, even if a global has the same name. The global is untouched.

count = 10 def reset():    count = 0                   # a new local count    print("inside:", count) reset()print("outside:", count)

inside: 0
outside: 10

The LEGB rule

When Python looks up a name, it searches four scopes in order and uses the first match:

x = "global" def outer():    x = "enclosing"    def inner():        print(x)          # not local, found in the enclosing function    inner() outer()print(len("built-in lookup"))

enclosing
15

The global keyword

To assign to a global variable inside a function, declare it with global:

counter = 0 def increment():    global counter    counter += 1 increment()increment()print(counter)

2

UnboundLocalError

If a function assigns to a name anywhere, that name is local for the whole function. Reading it before the assignment fails:

total = 100 def add_tax():    total = total * 1.18      # total is local here, but has no value yet    return total add_tax()

Traceback (most recent call last):
  File "main.py", line 7, in <module>
    add_tax()
    ~~~~~~~^^
  File "main.py", line 4, in add_tax
    total = total * 1.18      # total is local here, but has no value yet
            ^^^^^
UnboundLocalError: cannot access local variable 'total' where it is not associated with a value

The fix is to pass the value in: def add_tax(total): return total * 1.18.

nonlocal and closures

nonlocal lets an inner function assign to a variable of its enclosing function. The inner function keeps that variable alive even after the outer function has returned. This is called a closure.

def make_counter():    count = 0    def next_value():        nonlocal count        count += 1        return count    return next_value ticket = make_counter()print(ticket(), ticket(), ticket()) other = make_counter()        # a separate countprint(other())

1 2 3
1

Closures are useful for creating customised functions:

def make_multiplier(factor):    def multiply(x):        return x * factor    return multiply double = make_multiplier(2)triple = make_multiplier(3)print(double(5), triple(5))

10 15

Check your understanding

x = 1def f():    x = 2    def g():        nonlocal x        x = 3    g()    return xprint(f(), x)

3 1

10, then 20, then 60

10.0 15.0 30.0

def make_averager():    total = 0    count = 0    def add(value):        nonlocal total, count        total += value        count += 1        return total / count    return add avg = make_averager()print(avg(10), avg(20), avg(60))

10.0 15.0 30.0

Program Practice

Python scope FAQ