반응형
Python에서 ModuleNotFoundError 발생: 파일 이름과 패키지 이름이 충돌할 때
Python을 사용하다 보면 패키지를 정상적으로 설치했는데도 불구하고 ModuleNotFoundError가 발생하는 경우가 있습니다. 그 중 하나는 내가 만든 파일 이름이 설치한 패키지와 동일할 때 발생하는 문제입니다.
예를 들어, 다음과 같은 오류를 만난 적이 있습니다.
ModuleNotFoundError: No module named 'mypackage.graph'; 'mypackage' is not a package
처음에는 패키지 설치 문제인가 싶었지만, 원인은 단순했습니다. 프로젝트 루트 디렉토리에 mypackage.py라는 파일이 있었고, 이 파일이 실제 설치된 패키지보다 우선적으로 import 대상이 되어버린 것입니다. 결국 Python은 진짜 패키지를 찾지 못하고 "이건 패키지가 아니다"라는 오류를 던진 것이죠.
해결 방법: 이름 바꾸기
왜 이런 문제가 생기는가?
Python은 import 시에 다음 순서대로 모듈을 탐색합니다:
- 현재 실행 중인 스크립트가 위치한 디렉토리
- PYTHONPATH 환경 변수에 등록된 경로
- site-packages (pip으로 설치된 라이브러리)
따라서 내가 작성한 mypackage.py 파일이 프로젝트 루트에 있으면, 설치된 패키지 대신 이 파일을 먼저 읽어버립니다.
이 파일은 당연히 패키지가 아니므로 ModuleNotFoundError가 발생하게 됩니다.
해결 방법
- 파일 이름 변경하기
설치된 패키지와 동일한 이름을 쓰지 마세요.
예:- mypackage.py → my_project.py
- langgraph.py → graph_example.py
- 패키지를 명확하게 import하기
절대경로나 가상환경을 다시 확인하세요. 하지만 대체로 원인은 이름 충돌이므로 파일명을 바꾸는 것이 확실한 방법입니다. - 구조적으로 관리하기
프로젝트 루트에 패키지 이름과 겹칠만한 파일을 두지 말고, src/ 디렉토리 같은 구조를 활용하세요
ModuleNotFoundError가 난다고 해서 항상 패키지가 설치되지 않은 것은 아닙니다. 때로는 단순히 파일 이름 충돌이 원인일 수 있습니다.
Python은 현재 디렉토리를 최우선적으로 확인하기 때문에, 설치된 패키지와 같은 이름의 파일을 만들면 충돌이 일어납니다.
해결책은 간단합니다. 파일명을 바꿔라.
끝.
반응형
