Namespaces

Introduction

Every name you use in Python — a variable, a function, a class — has to live somewhere Python can look it up. That "somewhere" is called a namespace. You already learned, in the Variable Scope lesson, which namespace gets searched first when a name is looked up. This lesson focuses on something more fundamental: what a namespace actually is.

Once you see a namespace for what it really is — just a mapping of names to objects, conceptually a dictionary — a lot of Python's behavior becomes far less mysterious.

What is a Namespace?

A namespace is a mapping from names (as strings) to objects. Conceptually, it works exactly like a dictionary: each key is a name you have used in your code, like x or greet, and each value is the actual object that name currently refers to.

x = 10
name = "Alex"


def greet():
    pass


print(globals()["x"])
print(globals()["name"])
print(globals()["greet"])

10
Alex
<function greet at 0x000001A2B3C4D5E0>

This is not just a helpful analogy — globals() literally returns a real dictionary object representing the current global namespace. When you write x = 10, Python is effectively adding the entry "x": 10 into that dictionary.

Kinds of Namespaces

Python maintains several separate namespaces at once, each created at a different time and lasting for a different duration. The same name, like "x", can exist independently in more than one of these at the same time.

# built-in namespace already has: print, len, range, ...

count = 100  # lives in the global (module) namespace


class Robot:
    version = "v1"  # lives in the Robot class namespace


def process():
    count = 5  # a SEPARATE local namespace entry, unrelated to the global one
    print(count)


process()
print(count)
print(Robot.version)

5
100
v1

Notice that the local count inside process() and the global count are two entirely separate entries living in two entirely separate namespaces — changing one never touches the other.

Namespaces vs Scope

It is easy to blend these two ideas together, so it is worth being precise. A namespace is the mapping itself — the actual collection of name-to-object entries. Scope is the set of rules Python uses to decide which namespace to search first, second, and so on, when it looks up a name (this is the LEGB rule you covered in the Variable Scope lesson).

Inspecting Namespaces with globals() and locals()

Python gives you two built-in functions that return a namespace as an actual dictionary you can inspect: globals() for the module namespace, and locals() for whatever the current local namespace is.

language = "Python"
version = 3

names = globals()
print(type(names))
print("language" in names)
print(names["version"])

<class 'dict'>
True
3

def describe(item, price):
    tax = price * 0.1
    print(locals())


describe("Book", 20)

{'item': 'Book', 'price': 20, 'tax': 2.0}

Inside describe(), locals() shows exactly the local namespace at that moment: the two parameters and the tax variable created so far, all as one plain dictionary.

Module Namespaces

Every .py file you write gets its own private global namespace. This is why two completely different files can each define a variable called total or a function called process without ever colliding with each other.

# math_utils.py
def process(x):
    return x * 2

# text_utils.py
def process(text):
    return text.upper()

import math_utils
import text_utils

print(math_utils.process(5))
print(text_utils.process("hello"))

HELLO
10

Both files define a function named process, but because each module has its own separate namespace, math_utils.process and text_utils.process are completely distinct entries. You reach into each module's namespace using dot notation, exactly like reaching into a dictionary by key.

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

A namespace is simply where names live — a mapping of names to the objects they refer to, whether that is the built-in namespace, a module's global namespace, a function's local namespace, or a class's namespace. Keeping these separate is what allows the same name to be reused safely across different files and functions.

In this lesson, you learned what a namespace is, the different kinds Python maintains, how namespaces differ from scope, and how to inspect them directly with globals() and locals(). Next, you will learn comprehensions — a compact, readable way to build lists, sets, and dictionaries.