Python locals() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Built-in

Definition

In Python, locals() returns a dictionary of the local names in the current scope. Inside a function, that means its parameters and the variables assigned so far. At the top level of a module, locals() and globals() are the same dictionary.

Inside a function, treat the result as a read-only snapshot: writing to it does not change the real variables. Python 3.13 made this behaviour officially defined; earlier versions acted the same way for plain functions.

locals() is a built-in function: it lives in the builtins module, so it is always available without an import.

Syntax

It takes no arguments.

python
current = locals()
CallWhat it does
locals()Dict of the current local names.
"x" in locals()Is there a local named x?
"{a}".format(**locals())Format with local variables.
locals() is globals()True at module level.

Comprehensions and generator expressions have their own scope in Python 3, so a locals() call inside one sees only that scope.

Library declarations
python
locals()

Parameters

locals() takes no arguments.

Return Value

Return ValueDescription
dictThe current local names and their values.

Python Examples

Example 1 — See a Function's Local Variables

Return locals() from a function and inspect it.

python
def describe(name, age):
    city = "Oslo"
    return locals()


info = describe("Ana", 31)
print(info)
print(sorted(info))

How It Works

  1. Parameters first. name and age are locals from the moment the function starts.
  2. Assigned variables. city joins once it has been assigned.
  3. A real dict. The snapshot survives after the function returns and can be printed.
  4. Only locals. Globals such as describe itself are not included.

Example 2 — Fill a Template from Local Variables

Unpack locals() into str.format().

python
def report(item, qty):
    price = 2.5
    total = qty * price
    return "{qty} x {item} = {total}".format(**locals())


print(report("tea", 4))

How It Works

  1. Names as keys. Each local variable becomes a keyword argument for format().
  2. Unused keys are fine. price is passed but the template ignores it.
  3. Computed values. total is 4 × 2.5, a float, so it prints as 10.0.
  4. Modern alternative. An f-string, f"{qty} x {item} = {total}", does this without locals().

Example 3 — Writing to locals() Does Not Change Variables

Change the dict returned by locals() and check the real variable, then compare scopes at module level.

python
def try_to_change():
    x = 1
    snapshot = locals()
    snapshot["x"] = 99
    return x, snapshot["x"]


print(try_to_change())
print(locals() is globals())

How It Works

  1. Separate dict. Writing 99 into the snapshot changes only the dict.
  2. Variable unchanged. The real x is still 1.
  3. Module level. Outside any function, the local scope is the global scope, so both calls return the same dict.
  4. Change variables directly. Assign to x itself; locals() is for looking, not editing.

Frequently Asked Questions

A dictionary of the local names in the current scope: parameters and assigned variables inside a function.
No, not inside a function. Changes to the returned dict do not affect the real variables.
locals() is the current scope; globals() is always the module namespace. At module level they are the same.
Not inside a function. Only names local to that function appear.
Mostly for debugging and templating. Prefer explicit arguments or f-strings in production code.

Next: map()

Apply a function to every item, lazily.

map() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

13 people found this page helpful