파이썬 같은 이름 모듈이 sys.path 순서로 엉뚱하게 잡힐 때

먼저 결론

두 프로그램의 모듈을 한 프로세스에서 같이 쓰자 module 'config' has no attribute 'SITES_ROOT' 가 나거나, 예외 없이 기능 하나만 죽거나, 알림이 엉뚱한 로그 파일에 쓰였습니다. 두 코드 묶음에 같은 이름의 config.py, notify.py 가 있었고, sys.modules 캐시와 sys.path 순서 때문에 먼저 잡힌 사본이 쓰였습니다. 두 프로그램은 각각 별도 프로세스로 부르고, 꼭 같이 써야 하면 importlib.util.spec_from_file_location 으로 파일을 지정하고, 의심되면 모듈.__file__ 을 찍습니다.

파이썬의 import config 는 "config 라는 이름의 모듈"을 찾을 뿐, 어느 폴더의 config 인지는 묻지 않습니다. 이름이 같은 파일이 두 곳에 있으면 그중 먼저 잡힌 하나가 쓰이고, 나머지는 같은 프로세스 안에서 다시는 불리지 않습니다. 서버에서 두 프로그램을 함께 쓰다 이 때문에 여러 번 헤맨 기록입니다.

파이썬이 모듈을 고르는 순서

파이썬은 import 할 때 먼저 sys.modules 라는 캐시를 봅니다. 같은 이름이 이미 있으면 파일을 다시 찾지 않고 그것을 돌려줍니다. 캐시에 없을 때만 sys.path 의 폴더를 앞에서부터 차례로 뒤져 처음 찾은 파일을 씁니다(파이썬 공식 문서의 import system 설명).

그래서 같은 이름 문제는 두 갈래로 나타납니다. 이미 다른 사본이 캐시에 들어가 있는 경우, 그리고 sys.path 앞자리에 다른 폴더가 끼어든 경우입니다.

실제로 겪은 네 가지 모습

상황 겉으로 보인 것 잡힌 사본 헤맨 시간
A 의 모듈을 먼저, B 를 나중에 import AttributeError: ... 'SITES_ROOT' A 의 config 기록 없음
B 를 먼저, A 를 나중에 import 예외 없이 이미지 검색 하나만 죽고 다른 소스로 폴백 B 의 config 한 번 오진
파일 맨 위에서 B 폴더를 sys.path 0번에 넣음 알림이 B 의 로그 파일에 쓰임 B 의 notify 30분
시험 도구가 시작하자마자 라이브 폴더를 0번에 넣음 사본으로 한 시험이 전부 원본으로 돎 라이브 모듈 1.5시간

터지는 방향: 캐시에 남은 다른 config

프로그램 A(/opt/app_a)와 B(/opt/app_b)는 둘 다 config.py 를 갖고 있습니다. A 의 모듈은 안에서 import config as classifier_config 로 자기 config 를 불렀고, 이것이 sys.modules['config'] 에 들어갔습니다. 그 뒤 B 의 모듈이 import config 를 하자 캐시에 있던 A 의 config 를 받았습니다.

AttributeError: module 'config' has no attribute 'SITES_ROOT'

SITES_ROOT 는 B 의 config 에만 있는 값입니다. 이 방향은 바로 터지니 그나마 알아차리기 쉽습니다.

조용한 방향: 예외 없이 기능 하나만

순서를 바꿔 B 를 먼저 불러 본문을 읽고, 같은 프로세스에서 A 의 이미지 고르기 함수를 돌렸습니다. 이번에는 config 가 B 것으로 캐시돼, A 쪽 코드가 자기 설정 속성을 찾다 "그런 속성이 없다"는 오류를 냈습니다. 그런데 이 오류는 안쪽에서 처리되어 이미지 검색 소스 하나만 죽고 다른 소스로 넘어갔습니다.

배정은 정상으로 끝나고 사진도 나왔습니다. 그래서 결과만 보면 "이 소스가 원래 이 사진을 못 찾는구나"로 읽혔고, 실제로 한 번 그렇게 오진했습니다. 같은 코드를 B 없이 깨끗한 프로세스에서 돌리니 그 소스가 정확한 사진을 돌려주었습니다.

앞자리를 차지한 폴더

A 쪽 상태 수집 스크립트가 B 의 모듈을 쓰려고 맨 위에서 sys.path.insert(0, "/opt/app_b") 를 했습니다. 그러자 B 에도 있는 이름인 notify 가 B 의 사본으로 잡혔고, 그 사본의 로그 경로로 알림이 쓰였습니다. 상태는 갱신되는데 A 의 로그는 늘지 않아 "알림이 안 간다"며 30분을 헤맸습니다.

반대로 당한 일도 있습니다. 고친 모듈을 사본 폴더에 두고 PYTHONPATH 로 앞세워 시험했는데, 시험 도구가 시작하자마자 sys.path 맨 앞에 라이브 폴더를 넣고 있었습니다. 사본 시험 두 번이 전부 원본으로 돌았고, 그 결과를 수정 탓으로 읽어 1.5시간을 헛짚었습니다.

어느 파일이 잡혔는지 찍는다

네 경우 모두 한 줄이면 바로 드러났습니다.

import sys, config, notify
print(config.__file__, notify.__file__, file=sys.stderr)

파일에 쓰는 모듈이라면 그 모듈의 경로 상수(로그 경로 같은 것)를 같이 찍습니다. 사본으로 시험할 때는 시험을 돌리기 전에 이 줄부터 확인합니다.

같이 써야 할 때 고르는 방법

방법 언제 주의
각각 별도 subprocess 로 부르기 두 프로그램을 한 명령으로 묶을 때 가장 안전, 결과는 파일이나 표준 출력으로 넘긴다
spec_from_file_location 으로 파일 지정 한 프로세스에서 특정 사본이 꼭 필요할 때 다른 이름으로 등록해 캐시 충돌을 피한다
깨끗한 프로세스에서 재현 진단할 때 문제 모듈을 import 하지 않고, 입력은 미리 파일로 뽑아 둔다
import importlib.util as ilu
spec = ilu.spec_from_file_location("notify_a", "/opt/app_a/notify.py")
notify = ilu.module_from_spec(spec)
spec.loader.exec_module(notify)

이름이 notify_a 로 따로 등록되므로 B 의 notify 와 캐시에서 부딪히지 않습니다.

관련 글

오류가 안쪽에서 삼켜져 폴백만 도는 모습은 파이썬에서 실패가 조용히 삼켜지는 경우와 같은 계열입니다. 윈도우에서 재시작한 파이썬이 경로 때문에 죽는 일은 os.execv 재시작이 띄어쓰기 경로에서 죽을 때를 보세요.

이 글의 내용은 2026년 10월 10일에 마지막으로 확인했습니다. 틀린 곳을 발견하시면 연락처로 알려 주세요.