Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python's __main__ Guard Explained

Learn how Python's __main__ guard and a main() function control script entry points, and why they matter for scripts and importable modules.

~4 min readPython
#__main__#entry point#python scripts#module import
Illustration of a Python module entry point showing the `__main__` guard separating direct script execution from module import.

When the Python interpreter executes a file, it sets the module's __name__ attribute before running the code in that file. The value depends on whether the file is run directly or imported, and that single attribute is the foundation of the if __name__ == "__main__": guard that separates script execution from module import.

What __name__ Actually Contains

Every Python module has a built-in __name__ attribute. When a file is run directly, the interpreter sets __name__ to the string "__main__". When the same file is imported, __name__ is set to the module's name as it appears in the import statement.

Consider this file:

python
# module_a.py print(__name__)

Running it directly produces:

text
__main__

Importing it from another module produces:

text
module_a

That distinction is the entire basis for the entry-point guard. The value of __name__ is not a convention; it is assigned by the interpreter when the module is loaded.

Why the if __name__ == "__main__": Guard Matters

Without a guard, every statement at module level runs both when the file is executed directly and when it is imported. That is rarely what you want. A script that opens a database connection, starts a server, or prints output will do all of that work the moment another module imports it.

The guard restricts that behavior:

python
def main(): print("Running as a script") if __name__ == "__main__": main()

When python app.py runs this file, the interpreter reaches the if and finds __name__ equal to "__main__", so main() executes. When another module does import app, __name__ is "app", the condition is false, and only the function definition is loaded.

This is the core of the __main__ pattern: the same file behaves differently depending on how it is entered, and the guard is what controls that behavior.

Defining a main() Function

The common pattern is to keep the executable logic inside a main() function and reserve the guard for calling it. Keeping logic in a function rather than at module level has a practical benefit: the function can be imported and tested without side effects.

A typical entry point handles command-line arguments explicitly:

python
import sys def main(argv=None): if argv is None: argv = sys.argv[1:] for arg in argv: print(arg) return 0 if __name__ == "__main__": raise SystemExit(main())

The argv=None default makes the function testable without touching sys.argv. The raise SystemExit(main()) pattern converts the return value into an exit code, so a non-zero return signals failure to the shell. If you do not need an exit code, a plain main() call is sufficient.

Running as a Script vs. Importing

The table below summarizes the common entry paths for the same file:

How the file is enteredValue of __name__Does the guard run?
python file.py"__main__"Yes
python -m file"__main__"Yes
import file"file"No

The python -m form matters for packages. Running python -m mypackage executes the package's __main__.py module, which is the standard way to give a package a command-line interface without relying on a single script file.

The guard behaves identically in both direct and -m execution because the interpreter marks the entry module as "__main__" in both cases. The difference is how the module is located on the import path, not how __name__ is assigned.

Common Mistakes with the Entry Point

Several errors appear frequently when developers first work with the __main__ guard.

Putting all logic at module level is the most common one. A file that opens sockets or reads configuration at the top level will execute that work on import, which breaks tests and makes the module unsafe to reuse. Moving the work into main() and calling it from the guard fixes the problem.

Forgetting the guard entirely has the same effect. The file runs correctly when executed directly, but any import triggers the full script. This is especially visible in test suites that import modules for unit testing.

Calling exit() or sys.exit() inside main() instead of returning is a subtler issue. It works, but it makes main() harder to test because the call never returns normally. Returning an integer and letting the guard convert it to an exit code keeps the function composable.

Ignoring sys.argv is common in one-off scripts. If the script never needs arguments, that is fine. Once the script grows, threading sys.argv through main(argv) avoids global state and makes argument parsing testable.

Console Scripts and Package Entry Points

For code that ships as a package, the if __name__ == "__main__": guard is only half of the entry-point story. The other half is the console-script mechanism declared in pyproject.toml:

toml
[project.scripts] my-tool = "mypackage.cli:main"

When the package is installed, the tooling generates a small executable that imports mypackage.cli and calls its main() function. The generated wrapper includes the __name__ == "__main__" check, so the module itself does not need the guard to work as a command-line tool.

The guard still matters for the module. It lets python -m mypackage call main() at the right time while still allowing tests and the console script to import the module safely. Keeping the guard in place means the module remains importable without side effects even when it is also exposed as an installed command.

Keeping the Entry Point Maintainable

The long-term value of the __main__ pattern is testability. A module with a thin main() that delegates to small, named functions can be imported in tests without executing anything. Each function can be exercised directly, and the entry point itself is reduced to a one-line call.

A practical structure looks like this:

python
def load_config(path): ... def process(items): ... def main(argv=None): config = load_config(argv[0]) process(config) return 0 if __name__ == "__main__": raise SystemExit(main())

The guard keeps the boundary between "this file is a library" and "this file is a program" explicit. As the project grows, that boundary is what prevents import-time side effects from leaking into tests and into other modules that depend on the package.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.