파이썬 실행파일(.exe) 만들기 완벽 가이드

파이썬으로 프로그램을 만들었는데 다른 사람에게 공유하려니 난감했던 경험 있으신가요? “파이썬 설치하고 패키지 설치하고…” 이런 복잡한 과정 없이 더블클릭 한 번으로 실행되는 파일을 만들고 싶으시죠? 오늘은 파이썬 프로그램을 Windows, Mac, Linux 실행파일로 만드는 모든 방법을 알려드립니다.

Table of Contents

파이썬 실행파일이 필요한 이유

일반 사용자의 컴퓨터에는 파이썬이 설치되어 있지 않습니다. 여러분이 만든 프로그램을 배포하려면 다음 두 가지 방법이 있습니다.

사용자에게 파이썬 설치를 요구하는 방법 – 복잡하고 실패 확률이 높음
실행파일로 만들어 배포하는 방법 – 간편하고 전문적

실행파일로 만들면 파이썬이 없는 컴퓨터에서도 바로 실행됩니다. 프로그램 배포가 훨씬 쉬워지는 거죠.

2025년 최고의 도구: PyInstaller

과거에는 py2exe, py2app 같은 도구를 사용했지만, 2025년 현재는 PyInstaller가 가장 인기 있고 강력한 선택입니다. Windows, Mac, Linux를 모두 지원하고 사용법도 간단합니다.

PyInstaller 설치하기

pip install pyinstaller

단 한 줄로 설치가 완료됩니다. 별도의 복잡한 설정이 필요 없습니다.

기본 사용법 – 단일 파일 실행파일 만들기

가장 간단한 방법부터 시작해봅시다. hello.py 파일이 있다고 가정하겠습니다.

# hello.py
print("안녕하세요! 파이썬 실행파일입니다.")
input("엔터를 눌러 종료하세요...")

실행파일로 만들기:

pyinstaller --onefile hello.py

이게 전부입니다! dist 폴더에 실행파일이 생성됩니다.

Windows: hello.exe
Mac: hello (실행 권한이 있는 파일)
Linux: hello

GUI 프로그램 실행파일 만들기

Tkinter로 만든 GUI 프로그램이라면 콘솔 창이 뜨지 않게 만들 수 있습니다.

# calculator.py
import tkinter as tk

root = tk.Tk()
root.title("간단한 계산기")
root.geometry("300x400")

display = tk.Entry(root, font=("Arial", 20))
display.pack(pady=20)

root.mainloop()

Windows용 실행파일 만들기:

pyinstaller --onefile --noconsole calculator.py

-noconsole 옵션을 사용하면 검은 콘솔 창이 나타나지 않습니다.

아이콘 변경하기

전문적으로 보이려면 자체 아이콘이 필수입니다.

pyinstaller --onefile --noconsole --icon=app_icon.ico myapp.py

Windows: .ico 형식 필요
Mac: .icns 형식 필요

온라인 아이콘 변환 도구를 사용하면 PNG를 ICO로 쉽게 변환할 수 있습니다.

실전 예제: 완전한 프로그램 패키징

실제 프로젝트에서는 여러 파일과 리소스를 함께 패키징해야 합니다.

프로젝트 구조

my_project/
│
├── main.py
├── config.py
├── utils.py
├── icon.ico
├── data/
│   ├── settings.json
│   └── database.db
└── images/
    ├── logo.png
    └── background.jpg

리소스 파일 포함하기

pyinstaller --onefile --noconsole \\
    --icon=icon.ico \\
    --add-data "data/*:data" \\
    --add-data "images/*:images" \\
    main.py

Windows에서는 세미콜론(;) 사용:

pyinstaller --onefile --noconsole --icon=icon.ico --add-data "data/*;data" --add-data "images/*;images" main.py

숨겨진 임포트 추가하기

일부 라이브러리는 자동으로 감지되지 않습니다. 명시적으로 포함시켜야 합니다.

pyinstaller --onefile \\
    --hidden-import=requests \\
    --hidden-import=PIL \\
    main.py

spec 파일로 고급 설정하기

복잡한 프로젝트는 spec 파일을 사용하면 관리가 편합니다.

spec 파일 생성

pyi-makespec --onefile --noconsole main.py

main.spec 파일이 생성됩니다. 이 파일을 수정해서 세밀한 제어가 가능합니다.

spec 파일 예시

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=[
        ('data/*', 'data'),
        ('images/*', 'images'),
    ],
    hiddenimports=['requests', 'PIL'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)

pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    [],
    name='MyApp',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=False,
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon='icon.ico',
)

spec 파일로 빌드하기

pyinstaller main.spec

PyInstaller 주요 옵션 정리

옵션	설명	사용 예시
`--onefile`	단일 실행파일로 생성	가장 많이 사용
`--onedir`	폴더 형태로 생성 (기본값)	용량이 크지만 빠름
`--noconsole` / `--windowed`	콘솔 창 숨기기 (GUI용)	Windows GUI 필수
`--icon=파일명`	아이콘 설정	`.ico` 또는 `.icns`
`--name=이름`	실행파일 이름 지정	원본과 다른 이름
`--add-data`	데이터 파일 포함	이미지, 설정 파일 등
`--hidden-import`	숨겨진 임포트 추가	자동 감지 안 되는 모듈
`--exclude-module`	불필요한 모듈 제외	용량 줄이기
`--upx-dir`	UPX로 압축	실행파일 크기 감소
`--clean`	빌드 전 캐시 정리	오류 발생 시 사용

플랫폼별 배포 가이드

Windows 배포

Windows 실행파일은 가장 쉽습니다.

pyinstaller --onefile --noconsole --icon=app.ico main.py

주의사항:

Windows Defender가 의심스러운 파일로 감지할 수 있음
디지털 서명이 없으면 경고 메시지 표시 가능
인증서 구매 후 서명하면 신뢰도 향상

Mac 배포

Mac용 앱 번들을 만들려면:

pyinstaller --onefile --windowed --icon=app.icns main.py

.app 번들 만들기:

pyinstaller --windowed --icon=app.icns main.py

dist 폴더에 main.app 파일이 생성됩니다.

Mac 보안 설정:

macOS Gatekeeper 때문에 “신뢰할 수 없는 개발자” 경고 표시
Apple 개발자 계정으로 코드 서명 필요
또는 사용자가 “시스템 설정 > 보안”에서 허용해야 함

Linux 배포

Linux는 각 배포판마다 환경이 다를 수 있습니다.

pyinstaller --onefile main.py

배포 시 주의사항:

빌드한 배포판과 동일한 배포판에서 실행 권장
의존성 라이브러리 차이로 오류 발생 가능
AppImage 형식으로 만들면 호환성 향상

실행파일 크기 줄이기

PyInstaller로 만든 파일은 보통 크기가 큽니다. 줄이는 방법을 알아봅시다.

1. 가상환경 사용하기

가장 효과적인 방법입니다.

# 새 가상환경 생성
python -m venv venv

# 가상환경 활성화
# Windows
venv\\Scripts\\activate
# Mac/Linux
source venv/bin/activate

# 필요한 패키지만 설치
pip install pyinstaller
pip install 필요한패키지들

# 실행파일 생성
pyinstaller --onefile main.py

불필요한 패키지가 포함되지 않아 크기가 크게 줄어듭니다.

2. 불필요한 모듈 제외하기

pyinstaller --onefile \\
    --exclude-module tkinter \\
    --exclude-module matplotlib \\
    main.py

3. UPX 압축 사용하기

UPX는 실행파일 압축 도구입니다.

# UPX 다운로드 및 설치
# <https://upx.github.io/>

# PyInstaller에서 자동으로 사용됨
pyinstaller --onefile --upx-dir=/path/to/upx main.py

30-50% 정도 크기 감소 효과가 있습니다.

4. onedir 모드 고려하기

-onefile은 편리하지만 느립니다. -onedir은 폴더로 배포하지만 실행 속도가 빠릅니다.

pyinstaller --onedir --noconsole main.py

대안 도구들

PyInstaller 외에도 다양한 선택지가 있습니다.

1. cx_Freeze

크로스 플랫폼 지원, Python 3.11까지 완벽 지원

pip install cx_Freeze

setup.py 예시:

from cx_Freeze import setup, Executable

setup(
    name="MyApp",
    version="1.0",
    description="My Application",
    executables=[Executable("main.py", icon="icon.ico")]
)

빌드:

python setup.py build

2. Nuitka

파이썬을 C++로 컴파일하여 속도가 매우 빠름

pip install nuitka

nuitka --onefile --windows-disable-console main.py

장점:

실행 속도가 원본 파이썬보다 빠름
소스코드 역컴파일 방지

단점:

빌드 시간이 오래 걸림
일부 라이브러리 호환성 문제

3. py2exe (Windows 전용)

오래된 도구지만 여전히 사용 가능

pip install py2exe

setup.py:

from distutils.core import setup
import py2exe

setup(
    windows=[{'script': 'main.py'}],
    options={
        'py2exe': {
            'bundle_files': 1,
            'compressed': True,
        }
    },
    zipfile=None,
)

빌드:

python setup.py py2exe

4. py2app (Mac 전용)

Mac용 .app 번들 생성 전문 도구

pip install py2app

py2applet --make-setup main.py
python setup.py py2app

자주 발생하는 문제와 해결법

문제 1: ModuleNotFoundError

증상: 실행파일이 특정 모듈을 찾지 못함

해결:

pyinstaller --onefile --hidden-import=누락된모듈 main.py

문제 2: 파일을 찾을 수 없음

증상: 리소스 파일(이미지, 데이터)을 못 찾음

해결:

실행파일에서 경로를 올바르게 지정해야 합니다.

import sys
import os

def resource_path(relative_path):
    """ 리소스 파일의 절대 경로를 가져옵니다 """
    if hasattr(sys, '_MEIPASS'):
        # PyInstaller로 패키징된 경우
        base_path = sys._MEIPASS
    else:
        # 개발 환경
        base_path = os.path.abspath(".")

    return os.path.join(base_path, relative_path)

# 사용 예시
image_path = resource_path('images/logo.png')

문제 3: 실행파일이 너무 느림

증상: 실행 시작이 10초 이상 걸림

해결:

-onedir 모드 사용 (빠르지만 여러 파일)
가상환경에서 빌드해 불필요한 패키지 제거
spec 파일에서 debug=False 확인

문제 4: 안티바이러스가 차단함

증상: Windows Defender가 위험한 파일로 판단

해결:

디지털 서명 추가 (유료)
사용자에게 예외 추가 안내
VirusTotal에 업로드해 오탐 여부 확인

문제 5: DLL 파일 누락

증상: “VCRUNTIME140.dll not found” 오류

해결:

Visual C++ 재배포 패키지를 함께 배포하거나:

pyinstaller --onefile --collect-all 필요한라이브러리 main.py

배포 체크리스트

실행파일을 배포하기 전 확인해야 할 사항들입니다.

✅ 기능 테스트

모든 기능이 정상 작동하는지 확인
다른 컴퓨터에서 테스트 (파이썬 미설치 환경)
관리자 권한 없이 실행 가능한지 확인

✅ 리소스 확인

이미지, 설정 파일 등이 제대로 포함되었는지
데이터베이스 파일 경로 문제 없는지
폰트 파일 포함 여부

✅ 오류 처리

예외 상황 처리 코드 추가
로그 파일 생성 기능
오류 메시지 사용자 친화적으로 수정

✅ 보안 고려사항

민감한 정보 하드코딩 제거
API 키는 암호화 또는 별도 설정 파일
디버그 모드 비활성화

✅ 사용자 경험

적절한 아이콘 설정
프로그램 이름 명확하게
버전 정보 포함
설치/사용 가이드 문서 작성

실전 프로젝트: 완전한 예제

간단한 메모장 프로그램을 완전한 실행파일로 만들어봅시다.

notepad.py

import tkinter as tk
from tkinter import filedialog, messagebox
import sys
import os

def resource_path(relative_path):
    if hasattr(sys, '_MEIPASS'):
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.abspath("."), relative_path)

class Notepad:
    def __init__(self, root):
        self.root = root
        self.root.title("간단 메모장")
        self.root.geometry("800x600")

        # 아이콘 설정
        try:
            icon_path = resource_path('icon.ico')
            self.root.iconbitmap(icon_path)
        except:
            pass

        # 텍스트 영역
        self.text_area = tk.Text(self.root, font=("맑은 고딕", 12))
        self.text_area.pack(fill=tk.BOTH, expand=True)

        # 메뉴
        menubar = tk.Menu(self.root)
        self.root.config(menu=menubar)

        file_menu = tk.Menu(menubar, tearoff=0)
        menubar.add_cascade(label="파일", menu=file_menu)
        file_menu.add_command(label="열기", command=self.open_file)
        file_menu.add_command(label="저장", command=self.save_file)
        file_menu.add_separator()
        file_menu.add_command(label="종료", command=self.root.quit)

    def open_file(self):
        file_path = filedialog.askopenfilename(
            filetypes=[("텍스트 파일", "*.txt"), ("모든 파일", "*.*")]
        )
        if file_path:
            with open(file_path, 'r', encoding='utf-8') as f:
                content = f.read()
                self.text_area.delete(1.0, tk.END)
                self.text_area.insert(1.0, content)

    def save_file(self):
        file_path = filedialog.asksaveasfilename(
            defaultextension=".txt",
            filetypes=[("텍스트 파일", "*.txt"), ("모든 파일", "*.*")]
        )
        if file_path:
            with open(file_path, 'w', encoding='utf-8') as f:
                content = self.text_area.get(1.0, tk.END)
                f.write(content)
            messagebox.showinfo("저장 완료", "파일이 저장되었습니다.")

if __name__ == "__main__":
    root = tk.Tk()
    app = Notepad(root)
    root.mainloop()

빌드 명령어

pyinstaller --onefile --noconsole --icon=icon.ico --name=MyNotepad notepad.py

build.bat (Windows 자동화)

@echo off
echo 빌드를 시작합니다...

REM 이전 빌드 삭제
rmdir /s /q build dist

REM PyInstaller 실행
pyinstaller --onefile --noconsole --icon=icon.ico --name=MyNotepad notepad.py

echo 빌드가 완료되었습니다!
echo 실행파일 위치: dist\\MyNotepad.exe
pause

배포 패키지 만들기

단순히 실행파일만 주는 것보다 전문적인 배포 패키지를 만들어봅시다.

폴더 구조

MyNotepad_v1.0/
│
├── MyNotepad.exe
├── README.txt
├── LICENSE.txt
└── 사용설명서.pdf

Inno Setup으로 설치 프로그램 만들기

Windows용 설치 프로그램을 만들려면 Inno Setup이 유용합니다.

Inno Setup 다운로드: https://jrsoftware.org/isdl.php
스크립트 작성:

[Setup]
AppName=My Notepad
AppVersion=1.0
DefaultDirName={pf}\\MyNotepad
DefaultGroupName=My Notepad
OutputDir=output
OutputBaseFilename=MyNotepad_Setup

[Files]
Source: "dist\\MyNotepad.exe"; DestDir: "{app}"
Source: "README.txt"; DestDir: "{app}"

[Icons]
Name: "{group}\\My Notepad"; Filename: "{app}\\MyNotepad.exe"
Name: "{commondesktop}\\My Notepad"; Filename: "{app}\\MyNotepad.exe"

컴파일하면 MyNotepad_Setup.exe 생성

마치며

파이썬 프로그램을 실행파일로 만드는 것은 생각보다 간단합니다. PyInstaller를 사용하면 대부분의 경우 한 줄의 명령어로 해결됩니다.

핵심은 다음과 같습니다:

간단한 프로그램: pyinstaller --onefile main.py
GUI 프로그램: pyinstaller --onefile --noconsole main.py
리소스 포함: -add-data 옵션 사용
크기 최적화: 가상환경에서 빌드

이제 여러분의 파이썬 프로그램을 전 세계와 공유해보세요!

질문이나 문제가 있다면 댓글로 남겨주세요. 함께 해결해드리겠습니다!

파이썬 실행파일이 필요한 이유

2025년 최고의 도구: PyInstaller

PyInstaller 설치하기

기본 사용법 – 단일 파일 실행파일 만들기

GUI 프로그램 실행파일 만들기

아이콘 변경하기

실전 예제: 완전한 프로그램 패키징

프로젝트 구조

리소스 파일 포함하기

숨겨진 임포트 추가하기

spec 파일로 고급 설정하기

spec 파일 생성

spec 파일 예시

spec 파일로 빌드하기

PyInstaller 주요 옵션 정리

플랫폼별 배포 가이드

Windows 배포

Mac 배포

Linux 배포

실행파일 크기 줄이기

1. 가상환경 사용하기

2. 불필요한 모듈 제외하기

3. UPX 압축 사용하기

4. onedir 모드 고려하기

대안 도구들

1. cx_Freeze

2. Nuitka

3. py2exe (Windows 전용)

4. py2app (Mac 전용)

자주 발생하는 문제와 해결법

문제 1: ModuleNotFoundError

문제 2: 파일을 찾을 수 없음

문제 3: 실행파일이 너무 느림

문제 4: 안티바이러스가 차단함

문제 5: DLL 파일 누락

배포 체크리스트

실전 프로젝트: 완전한 예제

notepad.py

빌드 명령어

build.bat (Windows 자동화)

배포 패키지 만들기

폴더 구조

Inno Setup으로 설치 프로그램 만들기

마치며

참고 자료

관련

댓글 남기기 응답 취소