__name__ and __main__ behavior in Python - Deep Dive

Overview - __name__ and __main__ behavior

What is it?

In Python, __name__ is a special variable that holds the name of the current module. When a Python file runs directly, __name__ is set to '__main__'. This behavior helps the program know if it is being run as the main program or imported as a module in another file. It allows you to control which code runs in each case.

Why it matters

Without this behavior, every Python file would run all its code whenever imported, which can cause unwanted actions or errors. Using __name__ and '__main__' lets you write reusable code and scripts that behave differently when run directly versus when used as a library. This makes your code cleaner, safer, and easier to maintain.

Where it fits

Before learning this, you should understand basic Python scripts, functions, and modules. After this, you can explore Python packaging, testing frameworks, and writing command-line tools that use this behavior to run tests or main programs.

Mental Model

Core Idea

__name__ tells a Python file whether it is running directly or being imported, so it can decide what code to run.

Think of it like...

It's like a play script that knows if it's being performed on stage (run directly) or just being read for rehearsal (imported). The script can then choose to act out the play or just provide lines for others.

┌─────────────────────────────┐
│ Python file runs directly    │
│                             │
│ __name__ = '__main__'        │
│                             │
│ Run code inside if __name__  │
│ == '__main__' block         │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│ Python file imported as      │
│ module                      │
│                             │
│ __name__ = 'module_name'    │
│                             │
│ Skip code inside if __name__ │
│ == '__main__' block         │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding the __name__ variable

Concept: Learn what the __name__ variable is and what value it holds in different situations.

Every Python file has a built-in variable called __name__. When you run a Python file directly, __name__ is set to the string '__main__'. When you import that file as a module in another Python file, __name__ is set to the module's name (usually the filename without .py).

Result

You can check the value of __name__ to know if the file is running directly or imported.

Understanding __name__ is the foundation for controlling code execution depending on how the file is used.

2

Foundation

Using if __name__ == '__main__' block

Concept: Learn how to use the if __name__ == '__main__' condition to run code only when the file is executed directly.

You write code inside an if statement that checks if __name__ equals '__main__'. This code runs only when you run the file directly, not when you import it. For example: if __name__ == '__main__': print('Running directly') This prevents code from running during import.

Result

Code inside this block runs only when the file is the main program.

This pattern lets you separate code that should run as a script from code that should be reusable as a module.

3

Intermediate

How imports affect __name__ value

🤔Before reading on: When you import a Python file, do you think __name__ becomes '__main__' or the module's filename? Commit to your answer.

Concept: Understand that importing a file sets __name__ to the module's name, not '__main__'.

When you import a Python file, Python runs the file but sets __name__ to the module's name (usually the filename without .py). This means code inside if __name__ == '__main__' does NOT run during import. For example, importing mymodule.py sets __name__ to 'mymodule' inside that file.

Result

Code inside the if __name__ == '__main__' block is skipped during import.

Knowing this prevents accidental execution of script code when importing modules.

4

Intermediate

Using __name__ for testing and scripts

🤔Before reading on: Do you think the if __name__ == '__main__' block is useful only for scripts or also for testing? Commit to your answer.

Concept: Learn how to use the __name__ check to run tests or demo code only when running the file directly.

Developers often put test code or example usage inside the if __name__ == '__main__' block. This way, when you run the file, it tests itself or shows examples. But when imported, the tests or examples don't run, keeping imports clean.

Result

You can write self-testing modules or demo scripts without affecting imports.

This pattern improves code reuse and helps keep test/demo code separate from library code.

5

Advanced

Multiple files and __main__ interaction

🤔Before reading on: If you run a main.py that imports helper.py, what is __name__ in helper.py? '__main__' or 'helper'? Commit to your answer.

Concept: Understand how __name__ behaves across multiple files when one imports another.

When you run main.py directly, __name__ in main.py is '__main__'. When main.py imports helper.py, __name__ in helper.py is 'helper'. So, code inside if __name__ == '__main__' in helper.py does NOT run. This lets helper.py be a reusable module.

Result

Only the main file runs its '__main__' block; imported files skip theirs.

This behavior allows clear separation between main programs and reusable modules in multi-file projects.

6

Expert

Surprising behavior with python -m and packages

🤔Before reading on: When running python -m package.module, what is __name__ inside module.py? '__main__' or 'package.module'? Commit to your answer.

Concept: Learn how running modules with python -m affects __name__ and code execution.

When you run python -m package.module, Python sets __name__ in module.py to '__main__'. This means code inside if __name__ == '__main__' runs. This allows modules inside packages to be run as scripts. But if you import package.module normally, __name__ is 'package.module' and the block does not run.

Result

Running modules with -m triggers __main__ behavior even inside packages.

Understanding this lets you write modules that can be both imported and run as scripts inside packages, a key for complex projects.

Under the Hood

Python sets the __name__ variable automatically when it loads a module. If the module is the entry point of the program (the file you run), __name__ is set to the string '__main__'. For all other modules imported, __name__ is set to the module's name without the .py extension. This happens during the module loading process before any code runs, allowing conditional code execution based on __name__.

Why designed this way?

This design allows Python files to serve dual purposes: as reusable modules and as standalone scripts. Before this, scripts could not easily be imported without running all code, causing side effects. The __name__ and '__main__' pattern was introduced to solve this, making code modular and safe to import.

┌───────────────┐
│ Run python file│
│ directly       │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Python sets   │
│ __name__ =   │
│ '__main__'   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Execute code  │
│ including if  │
│ __name__ ==   │
│ '__main__'    │
│ block         │
└───────────────┘


┌───────────────┐
│ Import module │
│ in another    │
│ file          │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Python sets   │
│ __name__ =   │
│ 'module_name'│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Execute code  │
│ but skip if  │
│ __name__ ==   │
│ '__main__'    │
│ block         │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does code outside the if __name__ == '__main__' block run when importing a module? Commit to yes or no.

Common Belief: People often think that no code runs when a module is imported if it has an if __name__ == '__main__' block.

Reality: Code outside the if __name__ == '__main__' block runs immediately when the module is imported. Only code inside that block is skipped.

Why it matters: This can cause unexpected side effects or errors if initialization code runs on import unintentionally.

Quick: When running python -m module, is __name__ set to '__main__' or the module name? Commit to your answer.

Common Belief: Some believe that running python -m module sets __name__ to the module's name, not '__main__'.

Reality: Running python -m module sets __name__ to '__main__', triggering the if __name__ == '__main__' block.

Why it matters: Misunderstanding this leads to confusion about why code runs or doesn't run when using -m.

Quick: Does changing the filename of a module affect the value of __name__ inside it? Commit to yes or no.

Common Belief: People think __name__ is always '__main__' or fixed regardless of filename.

Reality: __name__ depends on the filename when imported; changing the filename changes __name__ accordingly.

Why it matters: This affects imports and can cause bugs if code relies on __name__ values.

Quick: Can you rely on __name__ to detect if code runs interactively in a REPL? Commit to yes or no.

Common Belief: Some believe __name__ is '__main__' in interactive Python sessions.

Reality: In interactive sessions, __name__ is '__main__', but the environment differs from running a script, so behavior can vary.

Why it matters: Assuming script-like behavior in REPL can cause confusion during testing or debugging.

Expert Zone

1

When stacking imports, only the first executed file gets __name__ == '__main__'; all others get their module names, which affects initialization order.

2

Using __name__ == '__main__' blocks in packages requires careful handling to avoid circular imports or unexpected side effects.

3

Some advanced tools and frameworks rely on __name__ to discover entry points or test modules dynamically.

When NOT to use

Avoid relying solely on __name__ == '__main__' for complex application entry points; use dedicated entry scripts or frameworks like setuptools entry points or CLI libraries for better control and clarity.

Production Patterns

In production, __name__ == '__main__' blocks often contain command-line interface code, test runners, or example usage. Libraries keep this block minimal or empty to avoid side effects. Complex projects use this pattern to separate reusable modules from executable scripts cleanly.

Connections

Module system in other languages

Similar pattern of distinguishing main program from imported modules

Understanding __name__ and __main__ in Python helps grasp how other languages handle module execution and entry points, like Java's main method or JavaScript's module exports.

Software design principle: Separation of concerns

The __name__ == '__main__' pattern separates script execution from module definition

This pattern embodies separation of concerns by isolating code that runs only when needed, improving modularity and maintainability.

Theatre performance roles

Both involve knowing when to perform (run) or stay silent (import)

Recognizing when code should 'perform' or stay 'silent' helps understand conditional execution and modular design beyond programming.

Common Pitfalls

#1 Running code outside the if __name__ == '__main__' block causes it to execute on import.

Wrong approach:

print('Hello')

# No if __name__ == '__main__' guard

# This runs on import

Correct approach:

if __name__ == '__main__':
print('Hello')

# Runs only when executed directly

Root cause:

Not understanding that all top-level code runs on import unless guarded.

#2 Assuming __name__ is always '__main__' inside imported modules.

Wrong approach:

def func():
if __name__ == '__main__':
print('Running')

# Importing this module runs the print

Correct approach:

def func():
if __name__ == '__main__':
print('Running')

# Importing skips the print

Root cause:

Confusing the value of __name__ when importing versus running directly.

#3 Using __name__ == '__main__' to control complex program flow or configuration.

Wrong approach:

if __name__ == '__main__':
setup_config()
run_app()
else:
setup_different_config()

Correct approach:

# Use dedicated config or CLI parsing instead
setup_config()
run_app()

Root cause:

Misusing __name__ for logic beyond entry point detection leads to fragile code.

Key Takeaways

__name__ is a special variable that tells a Python file if it is running directly or imported.

When running a file directly, __name__ is '__main__'; when importing, it is the module's name.

Using if __name__ == '__main__' lets you run code only when the file is executed as a script, not on import.

This pattern helps write reusable modules and scripts that can test or demonstrate themselves safely.

Understanding this behavior is key to organizing Python projects and avoiding unexpected code execution.