PyInstaller 패키징 시 "모듈을 찾을 수 없음" 오류 해결 방법

PyInstaller 패키징 시 "모듈을 찾을 수 없음" 오류 해결 방법

1. 개요

PyInstaller를 사용하여 Python 프로젝트를 실행 파일(EXE)로 패키징할 때, 특정 모듈을 찾을 수 없다는 오류가 발생할 수 있습니다. 이러한 문제는 여러 가지 원인으로 인해 발생하며, 해결 방법도 다양합니다.

이 글에서는 "ModuleNotFoundError"가 발생하는 주요 원인과 해결 방법을 단계별로 설명하고, 초보자도 쉽게 따라 할 수 있도록 예제 코드와 실용적인 팁을 제공하겠습니다.

---

2. 오류의 원인

PyInstaller 패키징 시 모듈을 찾지 못하는 대표적인 원인은 다음과 같습니다.

원인	설명
1. 숨겨진(import되지 않은) 모듈	코드에서 동적으로 불러오는 모듈(예: importlib.import_module)이 PyInstaller에서 감지되지 않음
2. 패키징 옵션 설정 문제	pyinstaller 실행 시 필요한 옵션을 추가하지 않아서 발생
3. 가상환경 문제	가상환경에서 설치된 패키지가 패키징 과정에서 누락됨
4. 경로 문제	실행 파일이 필요한 모듈을 올바르게 찾지 못하는 경우
5. PyInstaller의 hook 미지원	특정 라이브러리에 대한 PyInstaller의 자동 감지 기능 부족

---

3. 해결 방법

위에서 언급한 원인별로 해결 방법을 정리하면 다음과 같습니다.

3.1 숨겨진 모듈 처리

PyInstaller는 코드에서 직접 import한 모듈만 자동으로 감지합니다. 하지만 동적으로 불러오는 모듈(예: importlib.import_module)은 감지하지 못하므로, --hidden-import 옵션을 사용해야 합니다.

pyinstaller --onefile --hidden-import=my_module my_script.py

또는 spec 파일을 수정하여 추가할 수도 있습니다.

# my_script.spec 파일 수정
hiddenimports=['my_module'],

3.2 패키징 옵션 설정 문제 해결

PyInstaller 실행 시 필요한 옵션을 확인하고 추가합니다.

• 단일 실행 파일 생성: --onefile
• 콘솔 출력 숨기기(윈도우 GUI 앱): --noconsole
• 모듈 누락 방지: --hidden-import=모듈명
• 추가적인 데이터 파일 포함: --add-data="source:destination"

예제 실행 명령:

pyinstaller --onefile --noconsole --hidden-import=my_module my_script.py

3.3 가상환경 문제 해결

패키징 전에 가상환경을 활성화한 후, 해당 환경에서 PyInstaller를 실행합니다.

python -m venv myenv
source myenv/bin/activate  # (Windows의 경우 myenv\Scripts\activate)
pip install -r requirements.txt
pyinstaller --onefile my_script.py

3.4 실행 파일의 경로 문제 해결

실행 파일이 필요한 모듈을 찾지 못하는 경우, 실행 환경을 확인합니다.

• 현재 디렉토리에서 실행하는지 확인 (cd 명령 사용)
• sys.path를 출력하여 모듈이 올바른 경로에 있는지 확인
• --add-data 옵션을 사용하여 필요한 리소스를 포함

예제 코드:

import sys
print(sys.path)  # 실행 시 포함된 경로 확인

3.5 PyInstaller의 hook 미지원 해결

특정 라이브러리는 PyInstaller의 자동 감지 기능이 부족할 수 있습니다. 이 경우 PyInstaller의 hook을 수동으로 추가해야 합니다.

1. PyInstaller/hooks/hook-모듈이름.py 파일 생성
2. 필요한 모듈을 명시적으로 추가

예제 (hook-mymodule.py 파일 생성):

from PyInstaller.utils.hooks import collect_submodules
hiddenimports = collect_submodules('mymodule')

 

그 후 다시 pyinstaller 명령을 실행합니다.

반응형

---

4. 예제 코드 및 실행 방법

아래는 importlib을 사용하여 동적으로 모듈을 불러올 때 발생할 수 있는 오류를 해결하는 예제입니다.

4.1 문제 코드

import importlib

def load_module(module_name):
    return importlib.import_module(module_name)

module = load_module("my_module")  # 패키징 시 누락 가능성 있음
print(module)

4.2 해결 방법 적용

PyInstaller 실행 시 --hidden-import 옵션 추가:

pyinstaller --onefile --hidden-import=my_module my_script.py

또는 spec 파일 수정:

hiddenimports=['my_module'],

---

5. 결론

PyInstaller를 사용할 때 모듈을 찾을 수 없는 오류가 발생하는 원인은 다양하지만, 대부분의 경우 다음 방법으로 해결할 수 있습니다.

✅ --hidden-import 옵션을 활용하여 숨겨진 모듈 포함하기
✅ spec 파일을 수정하여 모듈을 명시적으로 추가하기
✅ 가상환경에서 패키징하여 필요한 패키지가 누락되지 않도록 하기
✅ 실행 파일의 경로 문제를 해결하기
✅ PyInstaller hook을 활용하여 자동 감지되지 않는 모듈 추가하기