Python if __name__ == "__main_

If you've studied Python, you've probably seen the mysterious if __name__ == "__main__" at the end of scripts and wondered what it really means. Why do some programs use it and others don't? This complete guide will answer all your questions.

The if __name__ == "__main__" construct is one of Python's most important patterns. It controls what happens when a Python file runs directly versus when it gets imported as a module. Understanding this mechanism is essential for writing professional, reusable, and well-structured code.

What Is the name Variable?

In Python, every time you run a file or import a module, the interpreter automatically sets a special variable called __name__. The value of this variable changes depending on how the file is being used.

How Python Sets name

When you run a Python file directly (for example, python my_script.py), the interpreter sets __name__ to the string "__main__". This tells you that the file is the main entry point of the program.

# file: my_script.py
print(f"Value of __name__: {__name__}")
Output when running: python my_script.py
Value of name: main

On the other hand, when you import the same file as a module in another script, Python sets __name__ to the module's own name (without the .py extension):

# file: my_script.py
print(f"Value of __name__: {__name__}")
In the interpreter:
>>> import my_script
Value of name: my_script

This subtle difference is the foundation of the entire if __name__ == "__main__" pattern. Python's official documentation explains this behavior in detail on the __main__ module page.

Understanding the if name == "main" Pattern

Now that you understand how __name__ works, the pattern becomes straightforward. The idea is simple: place code that should only run when the file is executed directly inside an if block:

def greet(name):
    """Return a personalized greeting."""
    return f"Hello, {name}!"
def main():
"""Main function of the program."""
name = input("Enter your name: ")
print(greet(name))
if name == "main":
main()

When you run this file directly, the condition is true, and main() gets called. When you import this file as a module in another program, the condition is false, and nothing runs automatically — you can call greet() manually with no side effects.

Why Is This Pattern So Important?

The if __name__ == "__main__" pattern solves a fundamental problem in Python development: separating executable code from reusable code. Without it, any code outside functions and classes would run at import time, potentially causing serious issues.

The Problem: Code Running During Import

# file: calculator.py
print("Calculator loaded!")
def add(a, b):
return a + b
def subtract(a, b):
return a - b
result = add(10, 5)
print(f"Test: {result}")

# file: app.py
import calculator  # This runs EVERYTHING in calculator.py!
total = calculator.add(3, 7)
print(f"Total: {total}")
Output:
Calculator loaded!
Test: 15
Total: 10

See the problem? When importing calculator, Python ran the test and print automatically. This pollutes the output and can cause unexpected behavior. The solution is to use the if __name__ == "__main__" pattern.

The Solution: Conditional Code

# file: calculator.py
def add(a, b):
    return a + b
def subtract(a, b):
return a - b
if name == "main":
print("Calculator loaded!")
result = add(10, 5)
print(f"Test: {result}")

Now, when importing calculator in app.py, nothing runs automatically — you only get access to the defined functions. The test only executes when the file runs directly.

Practical Use Cases

The if __name__ == "__main__" pattern is extremely versatile. Let's explore the most common and important use cases.

1. CLI Scripts (Command Line Interface)

One of the most powerful applications is creating scripts that accept command-line arguments using the argparse module:

import argparse
def process_file(path, verbose=False):
"""Process a file and return statistics."""
with open(path, 'r') as f:
lines = f.readlines()
if verbose:
    print(f"File: {path}")
    print(f"Total lines: {len(lines)}")

return len(lines)
if name == "main":
parser = argparse.ArgumentParser(
description="Process text files"
)
parser.add_argument(
"file",
help="Path to the file"
)
parser.add_argument(
"-v", "--verbose",
action="store_true",
help="Verbose mode"
)
args = parser.parse_args()
result = process_file(args.file, args.verbose)
print(f"Lines processed: {result}")

To use this script, you would run: python processor.py data.txt -v. The complete argparse documentation is available on the official Python documentation.

2. Built-in Unit Tests

You can include simple tests directly in the module that only run when the file is executed directly:

def calculate_mean(numbers):
    """Calculate the mean of a list of numbers."""
    if not numbers:
        return 0
    return sum(numbers) / len(numbers)
def calculate_median(numbers):
"""Calculate the median of a list of numbers."""
sorted_nums = sorted(numbers)
n = len(sorted_nums)
mid = n // 2
if n % 2 == 0:
    return (sorted_nums[mid - 1] + sorted_nums[mid]) / 2
return sorted_nums[mid]
if name == "main":
Simple tests
print("Running tests...")

# Mean test
assert calculate_mean([1, 2, 3, 4, 5]) == 3.0
assert calculate_mean([]) == 0
assert calculate_mean([10]) == 10

# Median test
assert calculate_median([1, 2, 3]) == 2
assert calculate_median([1, 2, 3, 4]) == 2.5
assert calculate_median([5]) == 5

print("All tests passed!")

3. Modules with Demo Code

You can include usage examples that serve as living documentation:

class Stack:
    """Implementation of a stack (LIFO)."""
def __init__(self):
    self._items = []

def push(self, item):
    self._items.append(item)

def pop(self):
    if self.is_empty():
        raise IndexError("Stack is empty")
    return self._items.pop()

def is_empty(self):
    return len(self._items) == 0

def size(self):
    return len(self._items)
if name == "main":
Usage demonstration
stack = Stack()
stack.push("A")
stack.push("B")
stack.push("C")

print(f"Size: {stack.size()}")  # 3
print(f"Pop: {stack.pop()}")  # C
print(f"Empty? {stack.is_empty()}")  # False
print(f"Pop: {stack.pop()}")  # B
print(f"Pop: {stack.pop()}")  # A
print(f"Empty? {stack.is_empty()}")  # True

Structuring Professional Scripts

How you structure your Python scripts greatly impacts code maintainability. The if __name__ == "__main__" pattern is the foundation for good structure.

The main() Function

The most adopted convention in the Python community is encapsulating the main logic in a function called main(). This follows the recommendations of PEP 8 — Python Style Guide and keeps the code organized.

import sys
import os
def setup_environment():
"""Configure environment variables and dependencies."""
os.environ.setdefault('APP_MODE', 'development')
return os.environ['APP_MODE']
def process_arguments():
"""Process and validate command-line arguments."""
args = sys.argv[1:]
if not args:
print("Usage: python script.py <file>")
sys.exit(1)
return args[0]
def execute(file_path):
"""Run the main program logic."""
mode = setup_environment()
print(f"Mode: {mode}")
print(f"Processing: {file_path}")
return True
def main():
"""Main function that orchestrates the program."""
path = process_arguments()
success = execute(path)
return 0 if success else 1
if name == "main":
sys.exit(main())

Organizing Imports

A well-structured script follows the PEP 8 recommended order for imports:

# 1. Standard library modules
import os
import sys
import json
from pathlib import Path
2. Third-party modules
import requests
import pandas as pd
3. Local modules
from my_package import utilities
def main():
... main logic
pass
if name == "main":
main()

The name Variable in Different Contexts

Let's explore how __name__ behaves in different scenarios to solidify your understanding.

Direct Execution

# test.py
print(f"__name__ = {__name__}")
Terminal:
$ python test.py
name = main

Import as Module

# test.py
print(f"__name__ = {__name__}")
Terminal:
$ python
>>> import test
name = test

Inside Packages

# package/__init__.py
print(f"__name__ in __init__: {__name__}")
package/module.py
print(f"name in module: {name}")
Terminal:
$ python
>>> import package.module
name in init: package
name in module: package.module

Understanding how Python's import system works is essential for mastering these concepts. The official documentation on the import system is highly recommended reading.

The main.py Module

An advanced related feature is the __main__.py file. When you create a Python package and include a __main__.py file in its directory, the package can be executed directly with python -m my_package.

This feature was introduced by PEP 338 — Executing Modules as Scripts and allows entire packages to be run as programs.

Example Structure with main.py

my_app/
├── __init__.py
├── __main__.py
├── utils.py
└── data/
    └── config.json

# __main__.py
from my_app import utils
def main():
print("Running my_app as a script!")
utils.load_config()
if name == "main":
main()

To execute: python -m my_app

Full documentation about the __main__ module and __main__.py file is available at the official Python documentation.

Running Modules with python -m

The python -m command is a powerful alternative for running Python modules. It executes a module as a script using module resolution instead of the file path.

# Equivalent to:
# python -c "import http.server; http.server.main()"
python -m http.server 8000
Run tests:
python -m unittest tests/test_calculator.py
Check syntax:
python -m py_compile my_script.py

The runpy module is the underlying mechanism Python uses to implement python -m. The runpy module documentation explains this process in detail.

Common Mistakes and How to Avoid Them

Even experienced developers make mistakes with the if __name__ == "__main__" pattern. Let's look at the most common ones.

1. Forgetting the Pattern in Shared Modules

# BAD: code runs on import
print("Utilities module loaded!")
data = load_heavy_file()  # This runs on import!
GOOD: use the pattern
def load_data():
return load_heavy_file()
if name == "main":
print("Utilities module loaded!")
data = load_data()

2. Using the Pattern When Not Needed

If a script will never be imported as a module, the pattern is unnecessary. One-off and throwaway scripts don't need it.

3. Putting Too Much Logic in the Global Scope

# BAD: logic scattered in global scope
if __name__ == "__main__":
    name = input("Name: ")
    age = int(input("Age: "))
    if age >= 18:
        print(f"{name} is an adult")
    else:
        print(f"{name} is a minor")
GOOD: logic encapsulated in functions
def check_adult(name, age):
if age >= 18:
return f"{name} is an adult"
return f"{name} is a minor"
def main():
name = input("Name: ")
age = int(input("Age: "))
print(check_adult(name, age))
if name == "main":
main()

4. Confusing name with Other Variables

__name__ is different from __file__ (file path) and __package__ (package name). Each has its specific purpose.

Best Practices and Advanced Tips

Now that you've mastered the fundamentals, here are some recommended practices to take your scripts to a professional level.

Always Define a main() Function

Even for small scripts, encapsulating the logic in main() makes testing and future reuse easier. This is a practice recommended by the Real Python tutorial on the main function.

Use sys.exit() with Error Codes

Error codes let other programs (shell scripts, CI/CD pipelines) know whether execution was successful:

def main():
    try:
        run_program()
        return 0  # Success
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1  # Error
if name == "main":
sys.exit(main())

Create Scripts with Entry Points

For more complex tools, consider using entry points with setup.py or pyproject.toml:

# pyproject.toml
[project.scripts]
my-app = "my_package:main"

This lets you run your program with just my-app in the terminal, without needing python or -m.

Comparison with Other Languages

The if __name__ == "__main__" pattern is Python's unique solution to a universal problem. Equivalent approaches in other languages include:

C/C++: The main() function is mandatory and always the entry point.
Java: The public static void main(String[] args) method in a specific class.
JavaScript (Node.js): The if (require.main === module) check.
Ruby: The if __FILE__ == $0 check.

Python chose an interpreter-variable-based approach, which offers great flexibility.

Debugging with name

The __name__ behavior is also useful for debugging. You can add conditional logging that only appears during direct execution:

import logging
logger = logging.getLogger(name)
def important_function(x, y):
result = x * y
logger.debug(f"important_function({x}, {y}) = {result}")
return result
if name == "main":
logging.basicConfig(level=logging.DEBUG)
# Tests
assert important_function(2, 3) == 6
assert important_function(-1, 5) == -5
print("Tests OK")

Framework Integration

Popular Python frameworks like Django and Flask use the if __name__ == "__main__" pattern to start development servers:

# Flask
from flask import Flask
app = Flask(name)
@app.route("/")
def home():
return "Hello, World!"
if name == "main":
app.run(debug=True)
Django (managed by manage.py)
if name == "main":
execute_from_command_line(sys.argv)

Python's import system and how it integrates with frameworks is an advanced topic worth studying. The official Python modules tutorial is the best starting point for going deeper.

Conclusion

The if __name__ == "__main__" pattern is one of Python's most elegant mechanisms. It allows a single file to work both as a reusable module and as an executable script, without conflicts or side effects.

Mastering this pattern is essential for any Python developer who wants to write professional code. It appears in virtually every quality Python project, from simple scripts to large frameworks like Django and Flask.

Remember the key points:

__name__ equals "__main__" when the file runs directly
__name__ equals the module name when imported
Always encapsulate the main logic in a main() function
Use sys.exit(main()) to return error codes
Consider creating __main__.py for executable packages

Continue your Python studies with these complementary guides:

Python Functions: Complete Guide — dive deeper into defining and using functions
Python Modules and Packages — understand how to organize code into modules and packages

For more content on Python and software development, keep following Universo Python!

Python if __name__ == "__main__": Complete Guide

📍 Sumário do Artigo

What Is the __name__ Variable?

How Python Sets __name__

Output when running: python my_script.py

Value of name: main

In the interpreter:

>>> import my_script

Value of name: my_script

Understanding the if __name__ == "__main__" Pattern

Why Is This Pattern So Important?

The Problem: Code Running During Import

Output:

Calculator loaded!

Test: 15

Total: 10

The Solution: Conditional Code

Practical Use Cases

1. CLI Scripts (Command Line Interface)

2. Built-in Unit Tests

Simple tests

3. Modules with Demo Code

Usage demonstration

Structuring Professional Scripts

The main() Function

Organizing Imports

2. Third-party modules

3. Local modules

... main logic

The __name__ Variable in Different Contexts

Direct Execution

Terminal:

$ python test.py

name = main

Import as Module

Terminal:

$ python

>>> import test

name = test

Inside Packages

package/module.py

Terminal:

$ python

>>> import package.module

name in init: package

name in module: package.module

The __main__.py Module

Example Structure with __main__.py

Running Modules with python -m

Run tests:

Check syntax:

Common Mistakes and How to Avoid Them

1. Forgetting the Pattern in Shared Modules

GOOD: use the pattern

2. Using the Pattern When Not Needed

3. Putting Too Much Logic in the Global Scope

GOOD: logic encapsulated in functions

4. Confusing __name__ with Other Variables

Best Practices and Advanced Tips

Always Define a main() Function

Use sys.exit() with Error Codes

Create Scripts with Entry Points

Comparison with Other Languages

Debugging with __name__

Framework Integration

Django (managed by manage.py)

if name == "main":

execute_from_command_line(sys.argv)

Conclusion

Share this article

Want to deepen your Python knowledge? 🚀

📚 Related Articles

Python in 2026: Why This is the Most Powerful Language in...

Python Enum: Complete Guide to Enumerations in Python

What Is Python Used For? Complete Python Applications Guide

Python if name == "main": Complete Guide

What Is the name Variable?

How Python Sets name

Understanding the if name == "main" Pattern

The name Variable in Different Contexts

The main.py Module

Example Structure with main.py

4. Confusing name with Other Variables

Debugging with name