The __name__ Variable

What Will You Learn
In this tutorial, you'll delve into Python's __name__ variable, understanding its role in distinguishing between direct script execution and module importation. You'll learn how to use the if __name__ == "__main__" construct to control code execution, enabling you to write more modular and reusable code. The guide includes practical examples and best practices to help you implement this concept effectively in your Python projects.

If you’ve been reading Python code for any amount of time, you've probably seen the line if __name__ == "__main__". It might seem cryptic at first, but this line is essential to writing flexible and reusable Python scripts. It helps control the execution flow and separates testing logic from the main functionality.

Understanding the __name__ variable allows you to write code that behaves differently depending on whether it’s being run directly or imported as a module. That’s a powerful feature — especially when building scripts, command-line tools, or reusable libraries.

By mastering the __name__ check, you’ll follow best practices used by professional developers and avoid running unwanted code when importing modules in larger projects.

What Is the __name__ Variable in Python?

The __name__ variable is a special built-in variable in every Python script. It holds a string that tells Python whether a script is being run as the main program or being imported as a module into another script. When the script is run directly, __name__ is set to "__main__". When it is imported, __name__ becomes the name of the module.

This behavior allows you to write conditional code that executes only when the file is run directly, not when imported.

It is commonly used to run tests, demos, or script-specific logic without affecting the behavior when used as a library.

Here are a few examples:

    # file: hello.py
    print(__name__)
    
    # Run directly → Output: __main__
    # Import in another script → Output: hello

    # file: math_utils.py
    def add(a, b):
        return a + b

    if __name__ == "__main__":
        print("Running test case:", add(2, 3))

    # file: main.py
    import math_utils
    print("Using add:", math_utils.add(5, 7))
    # Output will NOT include test case from math_utils.py

This approach helps you build reusable code without side effects when modules are imported.

How Does the __name__ Variable Work?

The __name__ variable in Python is automatically set by the interpreter. Its value depends on how the Python file is being used. If the script is executed directly, __name__ is set to "__main__". If the file is imported into another script as a module, __name__ takes the name of the module (the filename without .py).

This mechanism allows you to include logic in your code that only runs when the file is executed directly. It’s one of the cleanest ways to separate reusable components from executable logic.

Here's a quick python __name__ variable explanation in code:

    # file: test.py
    print("__name__ is:", __name__)

    # Run test.py directly → Output: __name__ is: __main__
    # Import test.py in another file → Output: __name__ is: test

    if __name__ == "__main__":
        print("This runs only when executed directly")

This is a simple yet powerful way to manage code execution across multiple files.

When and Why to Use if __name__ == "__main__"?

You use if __name__ == "__main__" to tell Python: "Run this block only if the script is executed directly, not imported." This is especially useful for test cases, demo code, or command-line entry points. It keeps reusable functions or classes separate from executable code and prevents side effects in other modules.

This python __name__ variable usage pattern is standard in professional codebases. It helps keep your code modular, testable, and clean.

Examples:

    def greet():
        print("Hello, world!")

    if __name__ == "__main__":
        greet()

    # Inside a script for testing functionality
    if __name__ == "__main__":
        print("Running tests...")

    # In production: only runs CLI logic when executed directly
    if __name__ == "__main__":
        main()

It’s a small line with a big impact — use it to keep your code clean and well-structured.

Common Mistakes with __name__ in Python

Forgetting to Use if __name__ == "__main__"

Beginners often write executable logic at the top level of the script without wrapping it inside if __name__ == "__main__". As a result, this code will run even when the file is imported, leading to unexpected behavior. For example, importing a module with database or network calls will trigger them unintentionally.

    # Mistake
    print("Connecting to server...")  # Executes on import

    # Fix
    if __name__ == "__main__":
        print("Connecting to server...")

Confusing __name__ with a Variable You Can Set

Some beginners think __name__ is a variable they should manually assign. In reality, Python automatically sets it — do not override it manually. Modifying __name__ breaks the import behavior and logic separation.

    # Wrong
    __name__ = "__main__"  # This does nothing useful

    # Correct
    if __name__ == "__main__":
        run()

Writing Logic Without Functions or Classes

If you place all your logic inside if __name__ == "__main__" without organizing it into functions or classes, your code becomes harder to reuse. The purpose of the main block is to call well-structured units — not contain the full program.

    # Poor practice
    if __name__ == "__main__":
        print("Step 1")
        print("Step 2")

    # Better
    def main():
        print("Step 1")
        print("Step 2")

    if __name__ == "__main__":
        main()

Expecting __name__ to Always Be "__main__"

Some assume that __name__ is always "__main__". This is only true when the script is executed directly. When imported, it reflects the module’s name. Failing to understand this leads to confusion when code inside if __name__ == "__main__" doesn’t execute.

    # file: helpers.py
    print(__name__)  # Output: helpers when imported

    # file: app.py
    import helpers

Running Test Code Outside the Main Check

Testing logic placed outside the __name__ block will run even during imports, which is not the intended behavior. This clutters output and can break importing scripts. Always isolate test cases using if __name__ == "__main__" to avoid accidental execution.

    # Wrong
    print("Running test case...")

    # Right
    if __name__ == "__main__":
        print("Running test case...")

Forgetting __init__.py When Using Packages

If you're organizing files into packages but forget to include an empty __init__.py file, Python may not treat the folder as a proper package. This affects how __name__ is assigned and can cause import failures or namespace issues.

    # Fix
    my_package/
    ├── __init__.py  # must be present
    └── module.py

Always include __init__.py to ensure modules behave as expected during imports.

Frequently Asked Questions — The __name__ Variable in Python