Python 프로그램을 EXE로 만드는 방법 — BAT 오류부터 PyInstaller onedir·onefile 직접 비교

Python으로 만든 업무 시간 계산기를 Windows에서 바로 실행할 수 있는 EXE로 변환해 봤습니다. 단순히 명령어만 정리한 글이 아닙니다. main.py 직접 실행부터 BAT 파일 오류, PyInstaller의 기본 onedir 빌드, 단일 파일인 onefile 빌드까지 실제로 만들고 실행한 결과를 순서대로 기록했습니다.

테스트 과정에서 BAT 파일의 한글 문구가 깨져 명령으로 잘못 해석되는 문제도 발생했습니다. 이를 영문 ASCII 문구와 안전한 Python 실행 순서로 수정한 뒤 정상 실행을 확인했습니다. 최종적으로 onedir에서는 main.exe와 _internal 폴더가 생성되었고, onefile에서는 약 11.7MB의 main.exe 한 개가 만들어졌습니다.

먼저 확인한 최종 결과

Python GUI 업무 시간 계산기 제작 및 main.py 실행 성공
run.bat 실행 시 한글 인코딩 문제 발생
BAT 문구와 실행 로직 수정 후 정상 실행
PyInstaller 기본 onedir 빌드 성공
dist\main 안의 main.exe + _internal 구조 확인
onefile 빌드 성공, 약 11.7MB의 단일 main.exe 확인
두 방식 모두 계산 기능과 최근 계산 기록 정상 작동

1. 테스트에 사용한 업무 시간 계산기

이번 테스트용 프로그램은 시작 시각과 작업 시간을 입력하면 종료 예정 시각을 계산하는 작은 Windows GUI 도구입니다. 예를 들어 16:08 + 15시간을 입력하면 다음 날 07:08을 표시합니다. 최근 계산 10개를 JSON 파일로 따로 저장하도록 만들었기 때문에 빌드 방식을 바꿔도 기록이 유지됩니다.

Python 업무 시간 계산기에서 16시 08분에 15시간을 더해 다음 날 07시 08분을 계산한 화면 — 시작 시각과 작업 시간을 계산하고, 자정을 넘으면 ‘다음 날’로 표시한 실제 실행 화면입니다.

Python이 설치된 개발 PC에서는 다음처럼 바로 실행할 수 있습니다.

python main.py

하지만 다른 사람에게 배포할 때마다 Python 설치와 명령어 입력을 요구할 수는 없습니다. 그래서 먼저 BAT 파일을 만들고, 그다음 PyInstaller로 EXE 변환을 진행했습니다.

2. run.bat 실행 실패: Python 문제가 아니라 문자 인코딩 문제였습니다

처음 만든 run.bat를 더블클릭했을 때 계산기가 열리지 않았습니다. 검은 명령 프롬프트에는 'el'은 내부 또는 외부 명령이 아닙니다처럼 의미를 알기 어려운 오류가 여러 줄 나타났습니다.

Windows 명령 프롬프트에서 BAT 파일 한글 인코딩이 깨져 여러 명령 오류가 발생한 화면 — BAT 파일의 한글 안내 문구가 깨지면서 일부 문자가 명령어처럼 처리된 오류 화면입니다.

처음에는 Python PATH 문제를 의심했습니다. 그러나 오류 화면을 확인해 보니 핵심은 BAT 파일 안의 한글 문구였습니다. 저장 인코딩과 Windows 명령 프롬프트의 코드 페이지가 맞지 않아 한글이 깨졌고, 깨진 문자열 일부가 명령어로 해석된 것입니다.

수정한 방법

BAT 파일의 안내 문구를 영문 ASCII 문자만 사용하도록 변경했습니다.
Windows Python Launcher인 py를 먼저 찾았습니다.
py가 없으면 python 명령을 찾도록 했습니다.
%~dp0를 사용해 BAT 파일이 있는 폴더의 main.py를 실행했습니다.
실패할 경우 창이 바로 닫히지 않도록 pause를 넣었습니다.

@echo off
cd /d "%~dp0"

where py >nul 2>&1
if %errorlevel%==0 (
    echo [INFO] Running with Python Launcher: py
    py "%~dp0main.py"
    goto :end
)

where python >nul 2>&1
if %errorlevel%==0 (
    echo [INFO] Running with command: python
    python "%~dp0main.py"
    goto :end
)

echo [ERROR] Python was not found.
pause

:end

수정 후에는 BAT 파일을 더블클릭했을 때 계산기가 정상적으로 열렸습니다. 이번 사례의 핵심은 “BAT가 실행되지 않으면 무조건 Python 재설치부터 할 것”이 아니라, 창을 닫지 않고 실제 오류 문구를 먼저 확인하는 것입니다.

3. PyInstaller 기본 빌드: onedir

BAT 파일은 실행을 편하게 해주지만 Python 자체를 포함하지 않습니다. Python이 설치되지 않은 Windows PC에서도 실행할 수 있는 배포본을 만들기 위해 PyInstaller를 설치했습니다.

python -m pip install pyinstaller

프로젝트 폴더에서 다음 명령을 실행하면 기본값인 onedir 방식으로 빌드됩니다.

pyinstaller main.py

PyInstaller 빌드 후 build와 dist 폴더, main.spec 파일이 생성된 프로젝트 폴더 — 기본 빌드 후 프로젝트 폴더에 build, dist, main.spec가 생성된 화면입니다.

실제 결과는 다음과 같았습니다.

프로젝트 폴더
├─ build
├─ dist
│  └─ main
│     ├─ main.exe
│     └─ _internal
├─ main.py
└─ main.spec

build는 빌드 과정의 작업 파일이 저장되는 곳이고, dist가 실제 배포 결과물입니다. main.spec는 빌드 구성을 담는 파일입니다.

PyInstaller onedir 빌드의 main.exe와 _internal 폴더 구조 — dist\main 안에 실행 파일과 지원 파일 폴더가 함께 생성된 onedir 구조입니다.

PyInstaller onedir 방식으로 만든 업무 시간 계산기 실행 화면 — onedir의 main.exe를 직접 실행해 계산 기능과 최근 기록 저장 영역을 확인한 화면입니다.

main.exe만 다른 위치로 옮기면 프로그램이 정상 실행되지 않을 수 있습니다. _internal을 포함한 main 폴더 전체가 하나의 배포 단위이기 때문입니다.

4. 단일 EXE 만들기: onefile

폴더 전체가 아니라 실행 파일 하나만 전달하고 싶다면 --onefile 옵션을 사용합니다.

pyinstaller --onefile main.py

빌드가 끝난 뒤 dist 폴더에는 약 11.7MB의 main.exe 한 개가 생성되었습니다.

PyInstaller onefile 빌드 후 dist 폴더에 약 11.7MB main.exe 한 개가 생성된 화면 — dist 폴더에 약 11.7MB의 main.exe 한 개만 생성된 onefile 결과입니다.

PyInstaller onefile 단일 EXE로 실행한 업무 시간 계산기와 최근 계산 기록 — 단일 EXE를 실행한 뒤 계산 기능과 기존 최근 기록이 유지되는지 확인한 화면입니다.

단일 파일이지만 실행 과정에서는 필요한 지원 파일을 임시 위치에 풀어 사용합니다. 따라서 환경에 따라 처음 창이 열리기까지 onedir보다 시간이 더 걸릴 수 있습니다. 이번 테스트에서는 실행 속도를 수치로 측정하지 않았으므로 속도 차이를 단정하지 않고, 두 방식 모두 정상 실행되는지만 확인했습니다.

5. BAT·onedir·onefile 직접 비교

방식	결과물	Python 설치	장점	주의점
main.py 직접 실행	Python 소스	필요	수정과 테스트가 가장 빠릅니다	배포용으로는 불편합니다
run.bat	BAT + Python 소스	필요	명령어 없이 더블클릭할 수 있습니다	PATH와 문자 인코딩 확인이 필요합니다
PyInstaller onedir	EXE + 지원 파일 폴더	불필요	파일 구조 확인과 문제 해결이 비교적 쉽습니다	폴더 전체를 배포해야 합니다
PyInstaller onefile	단일 EXE	불필요	전달과 보관이 간단합니다	실행 시 임시 압축 해제 과정이 있습니다

이번 업무 시간 계산기 제작 과정에서 확인한 네 가지 실행·배포 방식을 정리한 비교표입니다.

6. 어떤 방식을 선택하면 좋을까요?

개발 중이라면 main.py 또는 BAT

코드를 자주 수정하는 단계에서는 매번 EXE를 다시 만들 필요가 없습니다. 직접 실행하거나 BAT로 실행하는 편이 빠릅니다. 다만 BAT는 이번 사례처럼 인코딩과 Python 명령 인식 여부를 함께 확인해야 합니다.

내부 테스트와 오류 확인은 onedir

지원 파일이 분리되어 있어 빌드 결과를 확인하기 쉽습니다. 처음 PyInstaller를 적용할 때는 onedir로 정상 실행을 확인한 뒤 onefile로 넘어가는 순서가 안전합니다.

간단하게 전달하려면 onefile

받는 사람이 파일 하나만 실행하면 되므로 소규모 도구를 전달할 때 편리합니다. 다만 단일 EXE라는 이유만으로 모든 데이터가 EXE 안에 저장되는 것은 아닙니다. 이번 프로그램의 최근 기록은 사용자 폴더의 JSON 파일에 저장되므로 빌드 형식을 바꿔도 유지되었습니다.

7. 직접 해보며 확인한 핵심

오류 창이 바로 닫히지 않게 해야 실제 원인을 확인할 수 있습니다.
BAT 파일에서 한글을 쓸 때는 저장 인코딩과 콘솔 코드 페이지를 확인해야 합니다.
처음부터 onefile만 만들기보다 onedir로 먼저 실행 여부를 확인하는 편이 문제 해결에 유리합니다.
PyInstaller 빌드가 성공해도 반드시 생성된 EXE를 직접 실행해 기능을 다시 확인해야 합니다.
설정·기록 파일의 저장 위치는 EXE 형식과 별개로 설계해야 합니다.

이번 테스트는 main.py 직접 실행 → BAT 오류 확인 → BAT 수정 → onedir 빌드 → 폴더 구조 확인 → onefile 빌드 → 단일 EXE 실행 순서로 진행했습니다. 결과적으로 단순한 명령어 소개보다, 어디에서 실패할 수 있고 무엇을 확인해야 하는지가 더 분명해졌습니다.

참고자료

정리: 개발과 점검에는 onedir가 편했고, 전달 편의성은 onefile이 좋았습니다. 그러나 어떤 방식을 선택하든 “빌드 성공” 메시지만 믿지 말고 실제 EXE 실행, 기록 저장, 파일 구조까지 직접 확인하는 과정이 필요합니다.