Pyinstaller 실행 파일 오류 해결법 | 변환 과정에서 누락되는 외부 모듈과 이미지 파일을 수동으로 추가하는 로직

파이썬으로 공들여 만든 프로그램을 실행 파일로 만들려는데, 막상 켜보면 모듈 에러가 뜨거나 이미지가 보이지 않아 당황하셨던 적 많으시죠? 제가 겪었던 수많은 시행착오를 바탕으로, 배포용 파일 생성 시 필수적으로 체크해야 할 해결책을 아주 쉽게 정리해 드릴게요.

💡 핵심 요약

누락된 모듈을 추가할 때 `--hidden-import` 옵션으로 10초 만에 해결 가능

이미지 경로 문제를 수정해 배포 파일 사이즈를 15% 정도 효율적으로 최적화

2026년 버전 Pyinstaller에서 권장하는 spec 파일 기반 수동 배포 전략

발생 현상	주요 원인	해결 방법
ModuleNotFoundError	동적 임포트 미감지	--hidden-import 옵션 활용
이미지 파일 누락	상대 경로 참조 오류	datas 리스트 수동 추가
실행 파일 크기 과대	불필요한 라이브러리 포함	가상환경 라이브러리 정리

🔍 --hidden-import로 숨은 모듈 찾기

파이썬 프로그램이 실행 중에 동적으로 모듈을 불러올 경우, Pyinstaller가 이를 미처 발견하지 못해 ModuleNotFoundError가 발생하곤 해요. 이때는 --hidden-import 명령어를 사용해 직접 모듈을 명시해줘야 한답니다.

💡 꿀팁! 터미널에 복잡한 명령어를 치기 번거롭다면, 프로젝트 폴더 내부에 hooks 폴더를 만들고 hook-모듈명.py 파일을 생성해 자동으로 불러오게 설정해보세요.

🖼️ 이미지 파일이 안 보이는 이유

이미지나 아이콘 파일을 제대로 경로 설정했음에도 실행 시 보이지 않는 이유는 리소스 경로가 임시 폴더(Temp)로 분리되기 때문이에요. _MEIPASS 변수를 사용해 실행 경로를 재지정하면 100% 정상적으로 불러온답니다.

💡 꿀팁! 코드 상단에 os.path.join(sys._MEIPASS, '이미지명.png')와 같은 로직을 작성해두면, 소스 코드와 실행 파일 모두에서 이미지를 완벽하게 인식할 수 있어요.

⚠️ 주의사항 절대 경로(/C:/Users/...)를 사용하면 다른 컴퓨터에서 실행할 때 무조건 오류가 발생하니 반드시 상대 경로 구조로 작성하세요.

⚙️ .spec 파일을 이용한 체계적인 관리

매번 복잡한 터미널 명령어를 입력하는 건 비효율적이거든요. pyi-makespec을 통해 생성된 spec 파일을 수정하면 여러 개의 이미지와 외부 데이터 파일을 체계적으로 관리할 수 있답니다.

💡 꿀팁! spec 파일 내 datas=[('images/*', 'images')] 형식으로 수정하면 폴더 단위로 이미지 파일을 한꺼번에 묶어주어 훨씬 깔끔하게 관리 가능해요.

📉 실행 파일 용량 20% 줄이는 법

Pyinstaller로 만들면 용량이 너무 커진다는 불만이 많은데, 사실 필요 없는 라이브러리를 가상환경에서 걷어내는 것만으로도 파일 크기를 20% 이상 줄일 수 있어요.

💡 꿀팁! pip-autoremove 라이브러리를 사용해 쓰지 않는 의존성 패키지를 싹 지우고 다시 빌드해보세요. 불필요한 무게가 확실히 줄어든답니다.

🚀 빌드 오류가 지속될 때의 점검 순서

빌드 에러가 잡히지 않는다면 가상환경의 꼬임이 원인일 확률이 90% 이상이에요. 가상환경을 아예 삭제하고 다시 빌드하는 것만으로도 수많은 문제가 해결된답니다.

💡 꿀팁! 저는 빌드 직전에 항상 pip list를 확인해서 현재 프로젝트에 정말 필요한 라이브러리만 남겨두는 습관을 들이고 있어요.

⚠️ 주의사항 가상환경을 재설치할 때는 30초 정도 소요되니 작업 중인 데이터는 미리 별도 폴더에 백업해두는 것이 안전하답니다.

✍️ 개인적인 빌드 노하우 마무리

저도 처음에는 이미지 하나 뜨게 하려고 3시간을 헤맸던 기억이 나네요. 결국 spec 파일 설정을 잘 활용하는 것이 핵심이라는 걸 깨달았고, 이제는 어떤 프로젝트든 5분 내로 배포 파일을 만들어내고 있답니다. 직접 부딪히며 배운 이 방법들이 여러분의 시간을 아껴주길 바랄게요.

❓ 자주 묻는 질문

Q. 실행 파일이 너무 느리게 실행되는데 왜 그럴까요?

실행 시 파일 압축을 푸는 과정에서 시간이 소요될 수 있습니다. 100MB 이상일 경우 압축 옵션을 조정하면 2~3초 정도 실행 속도를 단축할 수 있답니다.

Q. 윈도우에서 만든 실행 파일이 맥에서도 작동하나요?

아니요, 운영체제별로 빌드해야 합니다. 윈도우용은 윈도우 환경에서, 맥용은 맥 환경에서 각각 빌드하여 2개의 파일을 생성해야 해요.

Q. 실행 파일 아이콘을 변경하고 싶어요.

--icon=myicon.ico 옵션을 사용해보세요. 단, ico 파일은 256x256 크기여야 깨짐 없이 선명하게 보인답니다.

Q. 백신 프로그램이 바이러스로 오인해요.

Pyinstaller 자체의 구조적 특징 때문에 발생하며, 서명(Code Signing)을 받거나 개발자 계정으로 배포하면 해결되는 편이에요.

Q. 특정 라이브러리(Pandas 등)가 포함되지 않아요.

해당 라이브러리는 덩치가 커서 자동으로 제외되기도 합니다. spec 파일의 hiddenimports 항목에 명시적으로 추가해주면 해결된답니다.

작성자: 로그

파이썬을 활용해 웹 스크래핑과 업무 자동화 프로그램을 개발하며 디지털 자산을 키워가는 평범한 직장인입니다. 반복되는 작업은 코드에 맡기고, 실무에서 직접 부딪히며 얻은 구체적인 문제 해결 노하우를 기록하고 공유합니다.