kind: capsule status: active visibility: private license: CC-BY-SA-4.0 summary: 스크립트 직접 실행과 모듈 import를 구분하는 가드. 누락 시 import 시점에 스크립트가 실행되는 부작용 발생. tags: - python - idiom - module - entry-point - capsule

Python `if name == "main"` Guard Capsule

Summary#

if __name__ == "__main__": 가드는 파일이 직접 실행될 때만 블록을 실행하고, import 될 때는 건너뛴다. 재사용 가능한 라이브러리 코드와 CLI 진입점을 한 파일에 공존시키는 표준 관용구.

Claim#

Python은 모듈 import 시 __name__ 을 모듈명으로, 스크립트로 직접 실행하면 "__main__"으로 설정
가드 없는 스크립트를 import하면 import 시점에 실행되어 CLI args·side-effects가 발동 — 거의 항상 버그
pickle unpickle은 클래스 정의 모듈을 import하므로 가드 없으면 역직렬화 시 원 스크립트가 실행
multiprocessing on Windows/macOS spawn: worker 프로세스가 entry 모듈을 import → 가드 없으면 무한 프로세스 생성 (fork-bomb)

표준 패턴:

def main():
    # ...
    pass

if __name__ == "__main__":
    main()

Scope#

CPython 2.x/3.x 공통
REPL·Jupyter 실행 시 __name__ == "__main__" 참 (노트북 셀을 모듈처럼 import하지 않는다면 의미 없음)

Caveats#

if __name__ == "__main__": 아래에 함수 정의·클래스 정의를 넣으면 import 시 정의되지 않아 혼란
python -m mypackage.mymodule 실행 시에도 __name__ == "__main__"
일부 정적 분석기는 가드 내부 코드 커버리지를 놓칠 수 있음

Source#

Q: https://stackoverflow.com/q/419163
A: https://stackoverflow.com/a/419185 — by Mr Fooz
License: CC BY-SA 4.0 (Stack Exchange)
last_edit: 2024
조회일: 2026-04-19

Sagwan Revalidation 2026-04-19T00:05:56Z#

verdict: ok
note: Python의 __name__ 동작 방식은 변하지 않았으며, 설명·예시·주의사항 모두 현재 practice에 부합한다.

Sagwan Revalidation 2026-04-20T00:43:55Z#

verdict: ok
note: Python의 __name__ 동작과 관련 주의사항(multiprocessing, pickle 등)은 변함없이 유효하다.

Sagwan Revalidation 2026-04-21T01:01:28Z#

verdict: ok
note: LLM unavailable: [CLI 오류 1] SessionEnd hook [node "/home/insu/.pixel-agents/hooks/claude-hook.js"] failed: node:internal/modules/cjs/load

Sagwan Revalidation 2026-04-22T01:31:54Z#

verdict: ok
note: LLM unavailable: [CLI 오류 1] SessionEnd hook [node "/home/insu/.pixel-agents/hooks/claude-hook.js"] failed: node:internal/modules/cjs/load

Python if __name__ == "__main__" Guard Capsule