Python __main__ explained

Vigneswaran SVigneswaran S
7 min read

Python Tutorial: Understanding if __name__ == "__main__":

Introduction

In Python, you often encounter a peculiar line of code: if __name__ == "__main__":. If you've wondered what it does and why it's so commonly used, you're in the right place! This tutorial will demystify this powerful idiom, explaining its purpose and showing you how to leverage it for more organized and reusable Python code.

What you'll learn:

  • What the __name__ special variable is.

  • How Python determines the value of name.

  • The role of if __name__ == "__main__": in controlling code execution.

  • Best practices for structuring your Python scripts.

Prerequisites

  • Basic understanding of Python syntax (variables, functions, if/else statements).

  • A Python interpreter installed on your system.

  • A text editor or an Integrated Development Environment (IDE) like VS Code, PyCharm, or even a simple text editor.

Step 1: The name Variable - Your Script's Identity

Every Python file (.py file) that the interpreter processes is considered a "module." When Python executes a module, it automatically defines a special built-in variable called name.

The value of name depends on how the module is being used:

  1. When a file is run directly (as the main script): Python sets the name variable for that file to the string "__main__".

  2. When a file is imported as a module into another file: Python sets the name variable for the imported file to its actual module name (which is usually the file's name without the .py extension).

Let's see this in action.

Exercise 1.1: Discovering name

  1. Create a new file named my_script.py.

  2. Add the following code to it:

Python

# my_script.py

print(f"Hello from my_script.py!")
print(f"The value of name is: {__name__}")
  1. Open your terminal or command prompt, navigate to the directory where you saved my_script.py, and run it:

Bash

python my_script.py

Expected Output:

Hello from my_script.py!
The value of name is: main

Explanation: When you run my_script.py directly, Python recognizes it as the primary script, so name inside my_script.py becomes "__main__".

Step 2: name When Imported

Now, let's see what happens to name when a file is imported.

Exercise 2.1: Importing a Module

  1. Keep my_script.py as it is.

  2. Create another new file named app.py in the same directory as my_script.py.

  3. Add the following code to app.py:

Python

# app.py

import my_script

print(f"\nHello from app.py!")
print(f"The value of name in app.py is: {__name__}")

# You can now access anything defined at the top level of my_script.py

# if it were a function or variable. For now, it just printed.

  1. Save app.py.

  2. Run app.py from your terminal:

Bash

python app.py

Expected Output:

Hello from my_script.py!
The value of name is: my_script
Hello from app.py!
The value of name in app.py is: main

Explanation:

    • When you ran python app.py, app.py became the main script, so its name was "__main__".

      • When app.py executed import my_script, the Python interpreter loaded my_script.py as a module. During this loading process, my_script.py's name was set to its module name, which is "my_script".

      • Notice that all the top-level code (like the print statements) in my_script.py executed when it was imported. This is an important observation!

Step 3: The Power of if name == "__main__":

The if __name__ == "__main__": block is a conditional statement that checks the value of the name variable. This allows you to define a block of code that will only execute when the script is run directly, and not when it's imported as a module.

This is incredibly useful for:

  • Providing a clear entry point: Signaling where the main logic of your script begins.

  • Preventing unintended execution: Ensuring that certain code (like setting up a database connection, running tests, or displaying user interfaces) only runs when the file is the primary script.

  • Making modules reusable: Allowing your Python files to be imported by other programs without triggering their standalone execution logic.

Exercise 3.1: Controlling Execution

  1. Modify my_script.py to include the if name == "__main__": block:

Python

# my_script.py
def greet(name):
    return f"Hello, {name}!"

print(f"This line always executes when my_script.py is loaded (directly or imported).")

if __name__ == "__main__":
    print(f"\nThis code runs ONLY when my_script.py is executed directly.")
    print(greet("World"))
    #You might put setup code, main application logic, or test calls here.
else:
    print(f"\nThis code runs ONLY when my_script.py is imported as a module.")
    print(f"__name__ in my_script.py is: {__name__}")

Modify app.py to call the greet function from my_script:

Python

# app.py
import my_script

print(f"\n--- From app.py ---")
print(f"The value of name in app.py is: {__name__}")
print(my_script.greet("Alice"))
  1. First, run my_script.py directly:

Bash

python my_script.py

Expected Output:

This line always executes when my_script.py is loaded (directly or imported).

This code runs ONLY when my_script.py is executed directly.

Hello, World!

Explanation: name was "__main__", so the code inside the if block executed.

  1. Now, run app.py:

Bash

python app.py

Expected Output:

This line always executes when my_script.py is loaded (directly or imported).

This code runs ONLY when my_script.py is imported as a module.

name in my_script.py is: my_script

--- From app.py ---

The value of name in app.py is: main

Hello, Alice!

Explanation:

    • When app.py imported my_script, my_script's name was "my_script".

      • Therefore, the if name == "__main__": condition in my_script.py was False, and the else block executed instead.

      • The greet function, which was defined at the top level, was still available for app.py to call.

This demonstrates the key benefit: you can have utility functions and classes in a file that are always available for import, but specific "run-the-application" logic only executes when that file is the main script.

Step 4: Common Patterns and Best Practices

A very common and recommended pattern is to define a main() function in your script and call it within the if __name__ == "__main__": block.

Exercise 4.1: Using a main() Function

  1. Create a new file named calculator.py.

  2. Add the following code:

Python

# calculator.py

def add(a, b):
    """Adds two numbers."""
    return a + b

def subtract(a, b):
    """Subtracts two numbers."""
    return a - b

def main():
    """
    The main function to run the calculator application.
    This code only runs when calculator.py is executed directly.
    """
    print("--- Simple Calculator App ---")
    num1 = float(input("Enter first number: "))
    num2 = float(input("Enter second number: "))

    print(f"Sum: {add(num1, num2)}")
    print(f"Difference: {subtract(num1, num2)}")
    print("---------------------------")

if __name__ == "__main__":
    main() # Call the main function to start the application
  1. Now, you can run calculator.py directly to use the calculator app:

Bash

python calculator.py

Expected Interaction:

--- Simple Calculator App ---

Enter first number: 10

Enter second number: 5

Sum: 15.0

Difference: 5.0

---------------------------
  1. Create another file, test_app.py, to demonstrate importing calculator.py:

Python

# test_app.py

import calculator

print("\n--- Testing calculator functions from test_app.py ---")
result_add = calculator.add(7, 3)
result_sub = calculator.subtract(10, 2) 

print(f"7 + 3 = {result_add}")
print(f"10 - 2 = {result_sub}")
print("-------------------------------------------------")
  1. Run test_app.py:

Bash

python test_app.py

Expected Output:

--- Testing calculator functions from test_app.py ---

7 + 3 = 10

10 - 2 = 8

-------------------------------------------------

Explanation:

    • When test_app.py imported calculator, the main() function within calculator.py was not executed because calculator.__name__ was "calculator", not "__main__".

      • However, the add and subtract functions were correctly imported and could be used by test_app.py.

This pattern provides excellent separation of concerns: your module defines reusable logic, and the if name == "__main__": block serves as the dedicated entry point for running that logic as a standalone application.

Summary and Key Takeaways

  • The name variable is a special built-in variable in Python that tells you how a module is being used.

  • If a script is run directly, name is set to "__main__".

  • If a script is imported as a module, name is set to the module's actual name (e.g., the file name).

  • The if name == "__main__": block is a standard Python idiom that allows you to:

    • Define code that only runs when the script is executed as the primary program.

    • Make your Python files reusable as modules by preventing the "main" execution logic from running on import.

  • It's a common best practice to encapsulate your primary application logic within a main() function and then call main() inside the if name == "__main__": block.

You now have a solid understanding of how if name == "__main__": works and why it's such an important concept in Python programming. Keep practicing and using this idiom in your projects to write cleaner, more modular, and more flexible code!

0
Subscribe to my newsletter

Read articles from Vigneswaran S directly inside your inbox. Subscribe to the newsletter, and don't miss out.

python mainpython namepython introPythoncodingPython basicspython learning#PythonLearningMy python learnings

Written by

Vigneswaran S
Vigneswaran S

With profound zeal, I delve into the essence of coding, striving to imbue it with beauty and clarity. Conjuring wonders through code is, to me, a delightful pastime interwoven with an enduring passion.