Python scripts execute top-to-bottom upon invocation, unlike compiled languages that mandate a specific entry function like main(). This dynamic execution model creates a conflict when a source file serves dual purposes: acting as an executable script and functioning as an importable library. The conditional block if __name__ == "__main__": resolves this ambiguity by controlling what executes during direct runs versus module imports.

Execution Contexts and Module Imports

When a .py file is executed directly via the interpreter, all top-level code runs immediately. Conversely, when imported into another script using import or from ... import ..., the entire file is parsed and executed during the import process unless explicitly guarded. Consider two files: config.py and calculator.py.

Unprotected config.py:

DEFAULT_THRESHOLD = 0.75

def validate_input(value):
    print(f"Validating {value} against threshold {DEFAULT_THRESHOLD}")
    return value > DEFAULT_THRESHOLD

validate_input(0.8)

Consumer script calculator.py:

from config import DEFAULT_THRESHOLD

def process_data(input_val):
    base_result = input_val * DEFAULT_THRESHOLD
    return base_result

result = process_data(10)
print(result)

Running calculator.py produces unexpected side effects because validate_input(0.8) executes during the import phase:

Validating 0.8 against threshold 0.75
7.5

To isolate test or demonstration logic, developers wrap execution-dependent blocks behind a runtime check:

Protected config.py:

DEFAULT_THRESHOLD = 0.75

def validate_input(value):
    print(f"Validating {value} against threshold {DEFAULT_THRESHOLD}")
    return value > DEFAULT_THRESHOLD

if __name__ == "__main__":
    validate_input(0.8)

Now, executing calculator.py cleanly outputs only 7.5. The conditional block evaluates to False during import, preventing the helper function from running. When invoked directly (python config.py), the condition becomes True, activating the enclosed logic.

The __name__ Runtime Attribute

The special variable __name__ holds the string representation of the current module's namespace. Its value shifts automatically based on how the interpreter encounters the file:

1. Direct Execution: When launched from the command line (python script.py), Python assigns "__main__" to __name__.
2. Module Import: When loaded via an import statement, __name__ takes the actual module identifier (e.g., "config").

This behavior extends to hierarchical packages. Given a directory structure:

data_processor/
├── __init__.py
└── helpers/
    ├── __init__.py
    └── transformer.py

Each __init__.py and transformer.py contains print(__name__). Executing python -c "import data_processor.helpers.transformer" yields:

data_processor
data_processor.helpers
data_processor.helpers.transformer

The output sequentially reveals the full dotted path, confirming that __name__ dynamically maps to the module's position within the project hierarchy. Conversely, running python data_processor/helpers/transformer.py directly prints just __main__, stripping away the package context.

The -m Flag and __main__.py Entrypoints

Python provides the -m flag to execute libraries or scripts as modules rather than standalone files. This flag alters environment variables, notably sys.path, and triggers specific initialization routines.

Compare two execution methods:

python app.py          # Direct execution
python -m app          # Module execution

Direct execution adds the script's directory to sys.path. Module execution adds the current working directory instead. Additionally, module execution first imports the target, ensuring proper namespace resolution before handing control over.

For packaged applications requiring a standardized CLI interface, Python looks for a __main__.py file inside the package directory. This file acts as the dedicated entry point when a package is invoked via python -m <package> or python <package>.

Example package layout:

analytics_engine/
├── __init__.py
└── __main__.py

analytics_engine/__init__.py:

import sys
print("Package initialization")
print(sys.path[:1])

analytics_engine/__main__.py:

import sys
print("Engine started via main module")
print(sys.path[:1])

Executing python -m analytics_engine produces:

Package initialization
['']
Engine started via main module
['']

The __main__.py script guarantees consistent bootstrapping behavior regardless of invocation syntax, making it ideal for distributing tools that need predictable initialization and path management. Wrapping core business logic behind if __name__ == "__main__": remains the standard practice for maintaining clean separation between library code and executable workflows.