`locals()`

The built-in locals() function returns a mapping object representing the current local symbol table, with variable names as the keys and their currently bound references as the values. This function is useful for inspecting the state of the local scope within a function or other local contexts:

>>> def add(a, b):
...     result = a + b
...     print(locals())
...     return result
...

>>> add(2, 5)
{'a': 2, 'b': 5, 'result': 7}
7

`locals()` Signature

locals()

Arguments

The built-in locals() function doesn’t take any arguments.

Return Value

Returns a mapping object representing the current local symbol table, with variable names as keys and their currently bound references as values.
In an optimized scope, which covers functions, generators, and coroutines, each call returns a fresh dictionary snapshot, and writing to it doesn’t modify the underlying local variables.
At module scope, it returns the same namespace as globals(), and at class scope, it returns the namespace passed to the metaclass constructor. In those scopes, changes made through the returned mapping are written through to the local variables.

`locals()` Examples

With a function to display local variables:

>>> def func(arg):
...     var = 100
...     print(locals())
...
>>> func(300)
{'arg': 300, 'var': 100}

When called in the global scope:

>>> locals() is globals()
True

`locals()` Common Use Cases

The most common use cases for the locals() function include:

Debugging to inspect variables and their values within a function
Inspecting local variables and their current values during execution. Note that in an optimized scope, which covers functions, generators, and coroutines, locals() returns a fresh dictionary snapshot of the current bindings, so writing to that dictionary does not modify the actual local variables. Python 3.13 and PEP 667 defined these semantics, which were previously undefined.
Understanding the scope and lifetime of variables within functions

`locals()` Real-World Example

You might want to log the state of local variables for debugging purposes when a function fails:

>>> def safe_divide(a, b):
...     try:
...         result = a / b
...     except ZeroDivisionError:
...         print("Error: Division by zero")
...         print("Local variables:", locals())
...         return None
...     return result
...

>>> safe_divide(10, 0)
Error: Division by zero
Local variables: {'a': 10, 'b': 0}

In this example, the locals() function provides a snapshot of the local variables when an error occurs, which can be invaluable for debugging.

Tutorial

Namespaces in Python

In this tutorial, you'll learn about Python namespaces, the structures that store and organize the symbolic names during the execution of a Python program. You'll learn when namespaces are created, how they're implemented, and how they support variable scope.

intermediate python

For additional information on related topics, take a look at the following resources: