PyInstaller는 파이썬 스크립트(.py 파일)를 윈도우(.exe), 맥(.app), 리눅스 등에서 파이썬 설치 없이도 바로 실행할 수 있는 독립적인 실행 파일로 만들어주는 아주 유용한 도구다.
PyInstaller의 기본적인 사용법과 알아두면 좋은 주요 옵션들을 정리해 보았다.
1. PyInstaller 설치
먼저 터미널(또는 명령 프롬프트)을 열고 pip를 이용해 PyInstaller를 설치해야 한다.
Bash
pip install pyinstaller
2. 가장 기본적인 사용법
실행 파일로 만들고자 하는 파이썬 파일이 있는 폴더로 이동한 뒤, 터미널에 아래와 같이 입력한다. (예시 파일명이 main.py인 경우)
Bash
pyinstaller main.py
이렇게 하면 폴더 안에 build와 dist라는 폴더, 그리고 main.spec이라는 파일이 생성된다.
우리가 원하는 최종 실행 파일은 dist 폴더 안에 만들어진다.
3. 알아두면 매우 유용한 주요 옵션들
그냥 기본 명령어로 만들면 관련 라이브러리 파일들이 주렁주렁 달리거나 쓸데없이 까만 콘솔창이 뜨는 등 불편한 점이 많다. 그래서 보통 아래의 옵션들을 조합해서 사용한다.
- -F 또는 --onefile (하나의 파일로 만들기):
이 옵션이 가장 많이 쓰인다. 여러 개의 파일과 라이브러리를 하나로 묶어서 단일 .exe (또는 실행) 파일 하나만 딱 만들어준다. 배포하기에 훨씬 깔끔하다.
Bash
pyinstaller -F main.py
* **`-w` 또는 `--noconsole` (콘솔 창 숨기기):**
GUI 프로그램(PyQt, Tkinter, PySide 등)을 만들었을 때 사용한다. 이 옵션을 넣지 않으면 프로그램을 실행할 때 까만 도스(cmd) 창이 뒤에 같이 뜨는데, 이를 보이지 않게 숨겨준다.
```bash
pyinstaller -w main.py
```
* **`-n 이름` 또는 `--name 이름` (출력 파일 이름 지정):**
만들어질 실행 파일의 이름을 파이썬 파일명과 다르게 지정하고 싶을 때 사용한다.
```bash
pyinstaller -F -n "MySuperApp" main.py
```
* **`-i 아이콘경로` 또는 `--icon 아이콘경로` (아이콘 설정):**
실행 파일의 아이콘(보통 `.ico` 파일)을 지정한다.
```bash
pyinstaller -F -i "my_icon.ico" main.py
```
### 4. 실전 종합 예시
GUI로 만든 파이썬 프로그램을, 아이콘을 넣어서, 단일 파일 하나로, 콘솔 창 없이 깔끔하게 만들고 싶다면 아래처럼 한 줄로 조합해서 사용하면 된다.
```bash
pyinstaller -F -w -i "app_icon.ico" -n "MyBestApp" main.py
4. 주의 및 참고 사항
- 용량 문제: -F (onefile) 옵션을 사용하면 파일 하나로 깔끔해지지만, 실행할 때 임시 폴더에 압축을 풀고 실행하는 과정을 거치기 때문에 초기 로딩 속도가 조금 느려질 수 있다.
- OS 종속성: 윈도우에서 PyInstaller를 실행하면 .exe 파일이 나오고, 맥에서 실행하면 맥용 실행 파일이 나온다. 윈도우에서 맥용 앱을 만들 수는 없으므로, 타겟 OS 환경에서 직접 빌드해야 한다.
- 외부 파일 포함: 프로그램 내부에서 이미지, 텍스트 파일, json 등 외부 데이터 파일을 읽어오는 경우, 기본적으로는 실행 파일 안에 포함되지 않는다. 이런 데이터 파일까지 실행 파일 안에 우겨넣으려면 .spec 파일을 직접 수정해야 하는 조금 더 복잡한 과정이 필요하다. (단순히 같은 폴더에 이미지 파일을 같이 두고 배포하는 방식을 먼저 권장한다.)
PyInstaller를 사용할 때 이미지, 텍스트, 설정 파일 등 외부 데이터 파일을 단일 실행 파일(.exe) 안에 함께 포함하려면 --add-data 옵션을 사용하거나 .spec 파일을 직접 수정해야 한다.
이 과정은 생각보다 까다로울 수 있는데, 가장 확실하고 대중적인 방법을 순서대로 설명해 주겠다.
5. 터미널(명령어)에서 --add-data 옵션 사용하기
간단하게 파일 한두 개를 포함할 때 사용하기 좋은 방법이다.
- 명령어 구조: --add-data "원본_경로;실행_파일_내부_경로"
- 주의사항: 윈도우에서는 경로 구분자로 세미콜론(;)을 쓰고, 맥이나 리눅스에서는 콜론(:)을 사용한다.
사용 예시 (윈도우 기준):
my_image.png라는 파일을 실행 파일과 같은 위치(.)에 포함시키고 싶다면 아래와 같이 입력한다.
Bash
pyinstaller -F -w --add-data "my_image.png;." main.py
만약 data라는 폴더 전체를 포함하고 싶다면 이렇게 한다.
Bash
pyinstaller -F -w --add-data "data/*;data" main.py
6. .spec 파일 수정하기 (권장)
포함해야 할 파일이나 폴더가 많아지면 명령어가 너무 길어져서 관리가 힘들다. 이때는 .spec 파일을 수정하는 것이 훨씬 깔끔하다.
- 먼저 기본 명령어로 빌드를 한 번 실행하여 main.spec 파일을 생성한다. (pyinstaller -F main.py)
- 생성된 main.spec 파일을 메모장이나 코드 에디터로 연다.
- Analysis 부분 안에 있는 datas=[] 항목을 찾아서 아래처럼 수정한다. (형식: ('원본 경로', '내부 경로'))
Python
a = Analysis(
['main.py'],
pathex=[],
binaries=[],
# 이 부분을 수정한다. 여러 개면 콤마로 구분한다.
datas=[
('my_image.png', '.'),
('config.json', '.'),
('data_folder', 'data_folder')
],
# ... 생략 ...
)
- 수정을 저장하고, 터미널에서 .py 파일 대신 .spec 파일로 다시 빌드한다.
Bash
pyinstaller main.spec
🚨 [가장 중요] 파이썬 소스코드 수정 (sys._MEIPASS)
많은 사람들이 파일 포함 옵션을 주고도 "파일을 찾을 수 없다"는 에러를 겪는다.
-F (단일 파일) 옵션으로 만든 프로그램은 실행될 때 내부에 포함된 파일들을 컴퓨터의 임시 폴더(Temp) 에 압축을 풀고 실행한다. 따라서 파이썬 코드 안에서 파일 경로를 읽을 때, 현재 폴더가 아니라 그 '임시 폴더'의 경로를 찾도록 코드를 수정해 주어야 한다.
파이썬 코드 최상단에 아래의 함수를 추가하고, 외부 파일을 불러올 때마다 이 함수를 거치도록 수정해야 한다.
Python
import os
import sys
def resource_path(relative_path):
""" 실행 파일 내부의 임시 폴더 경로를 반환하는 함수 """
try:
# PyInstaller에 의해 실행될 때 (임시 폴더 경로)
base_path = sys._MEIPASS
except Exception:
# 파이썬 원본 스크립트로 실행될 때 (현재 경로)
base_path = os.path.abspath(".")
return os.path.join(base_path, relative_path)
# --- 실제 사용 예시 ---
# 기존 코드: image_path = "my_image.png"
# 변경 코드: image_path = resource_path("my_image.png")
# 예: PySide6에서 이미지를 불러올 때
# pixmap = QPixmap(resource_path("my_image.png"))
이렇게 코드를 구성하면, 평소에 에디터에서 파이썬 코드를 테스트할 때도 정상적으로 작동하고, PyInstaller로 빌드한 후 .exe 파일로 실행할 때도 임시 폴더에서 파일을 정확하게 찾아오게 된다.
