Understanding Python's __main__

A guide to the common Python idiom if __name__ == '__main__':. Learn what this block of code does, why it's important, and how it allows you to write Python files that can be used as both runnable scripts and importable modules.

If you've spent time reading Python code, you have almost certainly come across this peculiar block of code at the end of a file:

if __name__ == '__main__':
    # some code here...

This is a very common idiom in Python, but for beginners, it can be confusing. What is __name__? What is __main__? And why is this if statement necessary?

Let's break it down.

The __name__ Variable

Every Python module has a special attribute called __name__. This is a built-in variable that the Python interpreter automatically sets. The value of __name__ depends on how the Python file is being used.

There are two main ways a Python file can be used:

  1. Run directly: You can run the Python file directly from the command line (e.g., python my_program.py).
  2. Imported: You can import the Python file as a module into another Python file (e.g., import my_program).

The Value of __name__

  • When you run a Python file directly, the interpreter sets the __name__ variable for that file to the string '__main__'.

  • When you import a Python file as a module, the interpreter sets the __name__ variable for that file to the name of the file itself (without the .py extension).

The if __name__ == '__main__' Idiom

Now, the if statement makes sense. The code inside the if __name__ == '__main__': block will only run when the file is executed directly. It will not run when the file is imported as a module into another script.

This allows you to create a Python file that can act as both a reusable module and a standalone script.

A Practical Example

Let's create a file called greeting.py with a function and our special if block.

# greeting.py

def greet(name):
    return f"Hello, {name}!"

# This block will only run when greeting.py is executed directly
if __name__ == '__main__':
    print("This file is being run directly.")
    message = greet("Alice")
    print(message)

Scenario 1: Run Directly

If we run this file from the command line:

python greeting.py

Here, __name__ is equal to '__main__', so the code inside the if block is executed. The output will be:

This file is being run directly.
Hello, Alice!

Scenario 2: Imported as a Module

Now, let's create another file, main_program.py, that imports greeting.py.

# main_program.py
import greeting

print("Running the main program.")
message = greeting.greet("Bob")
print(message)

If we run main_program.py:

python main_program.py

When the line import greeting is executed, the Python interpreter runs the greeting.py file. However, this time, because it's being imported, the __name__ variable inside greeting.py is set to 'greeting'. Since 'greeting' is not equal to '__main__', the code inside the if block in greeting.py is not executed.

The output will be:

Running the main program.
Hello, Bob!

Why is this a Best Practice?

This idiom is a best practice because it makes your code more modular and reusable. It allows you to:

  • Provide a library of functions and classes that other developers can import and use.
  • At the same time, provide a command-line entry point for demonstration, testing, or running the file as a standalone script.

Without this check, any code at the top level of your module (like the print and greet calls in our example) would run every time the module is imported, which is usually not what you want.

Conclusion

The if __name__ == '__main__': block is a fundamental and powerful feature of Python. It's the standard way to define the entry point of a Python script, providing a clear separation between the code that should be run when the file is executed directly and the code that should be exposed for other modules to import and use.