Python Main Guard: 5 Powerful Patterns You Must Know

You've written a handy script with a function others want to reuse. Someone imports it — and your script's test run fires off, charges test cards, and prints garbage into their logs. The import worked; everything around it broke.

That's the rite of passage behind Python's most-asked beginner question. Module-level code runs on import, unconditionally. Without a guard, your file can't tell 'borrow my function' from 'run my program.'

It's a two-line fix. You'll learn exactly what __name__ holds in each case, the five patterns that cover scripts to packages, and the multiprocessing trap that fires your guard twice if you're careless.

What __name__ Actually Holds in Each Case

Python sets one variable per module load: __name__. Direct run (python billing.py) → '__main__'. Import (import billing) → 'billing'. Package run (python -m shop.billing) → '__main__' again, but with package context for relative imports.

The guard compares that string. Equal → 'I'm the program, run main().' Unequal → 'I'm a library, just define things.' No magic, no framework — a string comparison executed once at load.

Prove it to yourself in 30 seconds: add print(__name__) at a file's bottom, run it directly (prints __main__), then import it from another shell (prints the filename). That experiment ends more confusion than any docs page.

Pattern 1-2: The Standard Guard + main(argv)

The canonical layout: imports and constants up top, function/class defs in the middle, def main(argv=None) holding program logic, and the two-line guard calling it with sys.exit for proper exit codes. argv=None lets tests inject argument lists without touching sys.argv.

Keep main() thin: parse args, configure logging, call one pipeline function, return an int. Business logic lives in testable functions (charge_all(customers, dry_run)), not inside main. Tests import functions; only humans and cron invoke main.

This shape also fixes the pytest-argparse collision: parse_args runs only under the guard, so collection imports never see CLI parsing. Every script in the repo should converge on this skeleton — consistency is a feature during incidents.

import argparse
import sys

CHARGE_LIMIT = 10_000  # constants at top level: safe


def charge_all(customers, dry_run=False):
    """Charge customers. Pure logic: easy to test, never runs on import."""
    results = []
    for c in customers:
        if dry_run:
            results.append((c, "skipped"))
        else:
            results.append((c, "charged"))
    return results


def main(argv=None):
    parser = argparse.ArgumentParser(description="Run billing charges.")
    parser.add_argument("--dry-run", action="store_true")
    args = parser.parse_args(argv)
    customers = ["user-1", "user-2"]  # real code loads from DB
    print(charge_all(customers, dry_run=args.dry_run))
    return 0


if __name__ == "__main__":
    sys.exit(main())

Pattern 3: Multiprocessing Without Double Execution

On spawn platforms (Windows, macOS default), each worker re-imports your module. Pool creation at top level therefore executes once per child — spawning workers that spawn workers, recursively, until the box falls over.

The fix is placement: worker functions at top level (importable by children), Pool/Process creation inside main() under the guard. Children import functions without running the program; only the parent runs main.

Linux fork historically masked this — children inherited memory without re-import. As macOS moved to spawn and Linux code goes cross-platform, unguarded process code is a portability landmine. Guard it now regardless of your current OS.

from multiprocessing import Pool


def render_chunk(chunk):
    """Worker: top level so children can import it."""
    return sum(chunk)


def main():
    data = [range(1000), range(1000, 2000)]
    with Pool(4) as pool:  # Pool creation UNDER the guard
        print(pool.map(render_chunk, data))


if __name__ == "__main__":
    main()

# WRONG: Pool() at module top level re-spawns on macOS/Windows.

Pattern 4: Packages, -m, and console_scripts

Packages add a wrinkle: python shop/billing.py breaks relative imports, while python -m shop.billing keeps package context and still triggers the guard. Standardize on -m in docs and runbooks so imports behave identically in dev and prod.

For installed tools, skip the guard dance at the call site: setuptools console_scripts / [project.scripts] generates an entry shim calling shop.billing:main. The guard remains in the module (for direct runs), but production invokes the installed command, which is cleaner in Docker images and cron.

Library modules that are never programs need no guard — but also need no side effects. If a library file grows a __main__ block for demos, keep the demo import-light so importing the library stays instant.

Pattern 5: Import-Time Safety Rules That Stick

Three rules make every module safe to import. No I/O at top level: no DB connects, no file writes, no thread pools outside functions. Constants and logging config are fine; connections are not — one service paid 900ms per gunicorn worker fork for a top-level connect.

No argv parsing at top level: parser.parse_args() belongs in main(argv). No heavy computation: precompute lazily or in main, not at import, so tab-completion and test collection stay instant.

Enforce mechanically: a CI test that imports every module in a subprocess with a network-blocked sandbox. If an import opens a socket or takes over a second, the PR fails. Culture follows tooling — the billing team hasn't had an import side effect since the gate landed.

What the Guard Doesn't Do (Myths to Drop)

The guard doesn't make code faster, thread-safe, or import-cycle-proof. Circular imports fail identically with or without it — the fix is restructuring, not gating. It also doesn't scope variables: names defined under the guard are still module globals after a direct run.

It doesn't replace entry points for installed apps, and it doesn't protect against exec(open().read()) tricks. It's one contract — direct-run versus imported — executed once. Expecting more breeds creative misuses like guarding individual functions (pointless) or nesting business logic three guards deep (unreadable).

Respect its size: two lines, one job. Architecture (idempotency keys, dry-run flags, sandbox tests) carries the reliability load the guard can't.