global

Any assignment inside a function makes that name local to the whole function. global name switches that off for one name: reads and writes go to the module namespace.

FunctionsPython 3 (all)Live demo
global
def f():
    global name
    name = value
several names
global a, b, c
Use for
Rebinding a module-level variable from inside a function
Result
a declaration — no value; affects how the compiler treats the name
Pairs with
nonlocal, def, module-level constants
Watch out
not needed to READ a global or to mutate it (append, item assignment) — only to rebind it

Demo

Live evaluation
bump rebinds the module-level count, so each call sees the previous total.
Try:
Inputs
stepslistcomma-separated
Code
count = 0
def bump(step):
    global count
    count += step
    return count
totals = [bump(s) for s in [1, 1, 1]]
(totals, count)
Result
([1, 2, 3], 3)

The without global tab is the classic surprise: Python decides at compile time that total is local to f because it is assigned somewhere in f. When the assignment is skipped, return total reads a local that was never set — UnboundLocalError, not the module value 10.

Syntax slots

NameTypeRequiredDescription
namenameyesOne or more identifiers. Must come before any use of the name in the same block; cannot be a parameter.

Common patterns

Module-level cache or config
Set once on first use.
_config = None

def get_config():
    global _config
    if _config is None:
        _config = load_config()
    return _config
Return instead of global
Usually cleaner: pass values in, return results out.
def bump(count, step):
    return count + step

count = bump(count, 1)
Mutation needs no global
Changing an object the global name refers to is not a rebinding.
registry = {}

def register(name, func):
    registry[name] = func

Examples

1. Reading a global needs no declaration
x = 5 def show(): return x show()
Returns
5
2. Rebinding needs global
x = 5 def reset(): global x x = 0 reset() x
Returns
0
3. Creating a global from a function
def setup(): global config config = {'debug': True} setup() config
Returns
{'debug': True}
4. Mutating is not rebinding
items = [] def add(v): items.append(v) add(1) items
Returns
[1]
5. global skips enclosing functions
x = 'module' def outer(): x = 'outer' def inner(): global x return x return inner() outer()
Returns
'module'
6. Declared too late
compile('def f():\n x = 1\n global x', '<demo>', 'exec')
Returns
SyntaxError: name 'x' is assigned to before global declaration
7. Used before the declaration
compile('def f():\n print(x)\n global x', '<demo>', 'exec')
Returns
SyntaxError: name 'x' is used prior to global declaration
8. A parameter cannot be global
compile('def f(x):\n global x', '<demo>', 'exec')
Returns
SyntaxError: name 'x' is parameter and global

Pitfalls

1. Updating a module variable with +=
count += 1 assigns, so count is local — and it is read before it has a value.
no declaration
count = 0
def bump():
    count += 1
bump()
UnboundLocalError: cannot access local variable 'count' where it is not associated with a value
global count
count = 0
def bump():
    global count
    count += 1
bump()
count
1
2. Using global for a variable of the enclosing function
global always means the module namespace. For a variable of an outer function, use nonlocal.
global
def outer():
    n = 0
    def inner():
        global n
        n = 1
    inner()
    return n
outer()
0
nonlocal
def outer():
    n = 0
    def inner():
        nonlocal n
        n = 1
    inner()
    return n
outer()
1

When to use

Use it
  • A small script’s module-level state (a counter, a lazily created resource)
  • Setting a module-level cache or configuration on first use
Reach for something else
  • Passing data between functions → parameters and return values
  • Shared state for a group of functions → a class instance
  • A variable of an outer function → nonlocal

Notes

CPython impl
Declared names compile to LOAD_GLOBAL / STORE_GLOBAL instead of LOAD_FAST / STORE_FAST
Scope
"Global" means the current module’s namespace — there is no cross-module global; other modules see it as module.name
Rule
Whether a name is local is decided per function at compile time: any assignment, for target, import, def or class binding it makes it local

FAQ

Declare it at the top of the function with global name, then assign to it. Without the declaration, the assignment creates a new local variable and the module-level one is unchanged.