PyInstaller를 활용한 Python 실행 파일 만들기: 완벽 가이드

Python으로 애플리케이션을 개발한 후, 다른 컴퓨터에서도 실행하려면 Python 인터프리터나 의존성 파일을 설치해야 합니다.

하지만 PyInstaller를 사용하면 Python 코드를 독립 실행 가능한 실행 파일(EXE)로 쉽게 만들 수 있습니다.

이번 포스트에서는 PyInstaller의 기본 사용법부터 유용한 옵션까지 자세히 설명하겠습니다.

 

---

 

PyInstaller란?

PyInstaller는 Python 스크립트를 실행 가능한 단일 파일 또는 디렉토리 형태의 실행 파일로 변환해 주는 도구입니다.

이 도구를 사용하면 Python이 설치되어 있지 않은 환경에서도 애플리케이션을 실행할 수 있습니다.

 

 

---

 

PyInstaller 설치하기

PyInstaller는 pip를 통해 간단히 설치할 수 있습니다.

pip install pyinstaller

 

설치 후, 다음 명령어를 통해 설치된 버전을 확인할 수 있습니다.

pyinstaller --version

 

---

 

PyInstaller 사용법

PyInstaller의 기본 명령어 형식은 다음과 같습니다.

pyinstaller [OPTIONS] script.py

 

1. 단일 파일 생성

Python 스크립트를 하나의 실행 파일로 생성하려면 --onefile 옵션을 사용합니다.

pyinstaller --onefile script.py

 

이 명령어는 dist 폴더에 단일 실행 파일을 생성합니다.

 

2. GUI 애플리케이션 생성

콘솔 창을 숨기려면 -w 또는 --noconsole 옵션을 추가합니다. GUI 애플리케이션 제작 시 유용합니다.

pyinstaller --onefile -w script.py

 

3. 실행 파일에 아이콘 추가

아이콘 파일은 .ico 형식이어야 하며, --icon 옵션을 사용하여 설정할 수 있습니다.

pyinstaller --onefile -w --icon=app.ico script.py

 

4. 외부 파일 포함

데이터 파일(예: 설정 파일, 이미지 파일)을 포함하려면 --add-data 옵션을 사용합니다.
Windows에서는 세미콜론(;), Linux/Mac에서는 콜론(:)으로 구분합니다.

pyinstaller --onefile --add-data "config.json;." script.py

 

위 명령은 config.json을 실행 파일에 포함시키고, 실행 시 현재 디렉토리에서 사용할 수 있도록 만듭니다.

 

5. 특정 모듈 제외

필요 없는 모듈을 제외하려면 --exclude-module 옵션을 사용합니다

pyinstaller --onefile --exclude-module numpy script.py

 

6. 숨겨진 모듈 포함

PyInstaller가 자동으로 탐지하지 못하는 모듈을 명시적으로 포함하려면 --hidden-import 옵션을 사용합니다.

pyinstaller --onefile --hidden-import "module_name" script.py

 

---

 

PyInstaller 옵션 정리

1. 파일 생성 관련 옵션

옵션설명

--onefile	모든 코드를 하나의 실행 파일로 만듭니다.
--onedir	실행 파일과 필요한 파일들을 하나의 폴더에 생성합니다. (기본 옵션)
--name NAME	생성될 실행 파일 이름을 지정합니다. (기본값은 스크립트 이름)
--clean	이전 빌드에서 생성된 임시 파일을 삭제하고 새로 빌드합니다.
--icon FILE.ico	실행 파일의 아이콘을 설정합니다. (파일은 .ico 형식이어야 합니다)

2. 리소스 포함 관련 옵션

옵션설명

--add-data "SRC;DEST"	외부 데이터 파일/폴더를 실행 파일에 포함. Windows: ;, Linux/Mac: : 사용.
--add-binary "SRC;DEST"	바이너리 파일을 실행 파일에 포함. Windows: ;, Linux/Mac: : 사용.
--paths PATH	추가적인 모듈 검색 경로를 설정합니다.
--exclude-module MODULE	빌드에서 특정 모듈을 제외합니다.
--hidden-import MODULE	PyInstaller가 자동으로 찾지 못하는 모듈을 명시적으로 추가합니다.

3. 실행 파일 동작 설정

옵션설명

-w 또는 --noconsole	콘솔 창을 숨깁니다. (GUI 애플리케이션에 적합)
-c 또는 --console	콘솔 창을 활성화합니다. (CLI 애플리케이션에 적합, 기본 옵션)
-f 또는 --onefile	하나의 실행 파일로 만듭니다.
--debug	디버그 정보를 활성화합니다.

4. 빌드 설정 및 최적화

옵션설명

--upx-dir UPX_PATH	UPX 압축을 사용할 경우 UPX 실행 파일 경로를 지정합니다.
--noupx	UPX 압축을 비활성화합니다.
--strip	생성된 실행 파일에서 불필요한 심볼 정보를 제거하여 크기를 줄입니다.
--key KEY	AES 암호화를 사용하여 소스를 보호합니다. KEY는 암호화 키를 지정합니다.

5. 빌드 환경 설정

옵션설명

--distpath DIR	생성된 실행 파일이 저장될 디렉토리를 지정합니다. 기본값은 ./dist.
--workpath DIR	빌드 중 생성되는 임시 작업 디렉토리를 지정합니다. 기본값은 ./build.
--specpath DIR	.spec 파일이 저장될 경로를 지정합니다. 기본값은 현재 디렉토리.

 

---

 

PyInstaller 결과 파일 설명

1. dist/
   • 생성된 실행 파일이 저장되는 폴더입니다.
   • --onefile 옵션 사용 시 단일 파일(EXE), --onedir 옵션 사용 시 디렉토리가 생성됩니다.
2. build/
   • 빌드 과정에서 생성된 임시 파일이 저장되는 폴더입니다.
   • 필요하지 않으면 삭제해도 됩니다.
3. .spec 파일
   • PyInstaller의 설정 파일입니다. 나중에 동일한 설정으로 재빌드할 수 있습니다.

 

pyinstaller your_script.spec

 

위와 같이 .spec 파일을 사용해 빌드할 수 있습니다.

 

---

 

PyInstaller 빌드 예제

1. 기본 실행 파일

pyinstaller script.py

2. 단일 파일로 생성

pyinstaller --onefile script.py

3. GUI 애플리케이션

pyinstaller --onefile -w --icon=app.ico script.py

4. 외부 파일 포함

pyinstaller --onefile --add-data "config.json;." script.py

5. 모든 설정 적용

pyinstaller --onefile --noconsole --icon=app.ico --add-data "config.json;." script.py

 

---

 

문제 해결 및 디버깅

 

1. 실행 중 에러 발생

• --debug 옵션으로 디버깅 정보를 활성화해 원인을 확인하세요.

pyinstaller --onefile --debug script.py

 

2. 리소스 파일 경로 문제

• 실행 파일에서 리소스 경로를 올바르게 설정하려면 sys._MEIPASS를 사용해야 합니다.

def resource_path(relative_path):
    base_path = getattr(sys, '_MEIPASS', os.path.dirname(os.path.abspath(__file__)))
    return os.path.join(base_path, relative_path)

 

3. 파일 크기 줄이기

• UPX를 사용해 실행 파일 크기를 줄일 수 있습니다.

pyinstaller --onefile --upx-dir /path/to/upx script.py

 

---

 

결론

PyInstaller는 Python 프로젝트를 독립 실행 파일로 배포하는 데 강력한 도구입니다.
필요한 옵션을 적절히 활용하면 다양한 환경에서 애플리케이션을 쉽게 실행할 수 있습니다.