• “파이썬 설치해야 해?”
• “pip로 뭐 설치해야 해?”
• “실행했더니 검은 창만 뜨고 꺼지는데?”

그래서 결국 많이 선택하는 방법이 EXE로 패키징하는 겁니다.
이번 글은 제가 실제로 가장 많이 쓰는 도구인 PyInstaller 기준으로, “초보도 따라 할 수 있게” 정리했습니다.

1) EXE 만들기 전에 꼭 알아야 할 것

✅ EXE로 만들면 좋은 점

• 파이썬이 설치되지 않은 PC에서도 실행 가능(대부분의 경우)
• 배포/공유가 편해짐
• 파일 1개(또는 폴더 1개)로 정리 가능

⚠️ 현실적으로 생기는 문제

• 용량이 커짐(수십~수백 MB도 흔함)
• 백신 오탐(특히 새로 만든 exe)
• 경로 문제(파일 저장/설정 파일 위치)
• GUI(Tkinter 등)에서는 괜찮은데, 콘솔 출력은 안 보이기도 함

이걸 미리 알고 가면 삽질이 크게 줄어요.

2) 준비물: 파이썬/폴더 구조 추천

권장 폴더 구조 예시

my_app/
  main.py
  core/
  assets/
  data/
  requirements.txt

• assets/ : 이미지, 아이콘 등 리소스
• data/ : 설정 파일, 저장 파일(앱 실행 중 생성되는 데이터)
• requirements.txt : 의존성 목록

3) PyInstaller 설치

가장 먼저 가상환경을 추천합니다. (빌드가 깔끔해져요)

(선택) 가상환경 만들기

cd my_app
python -m venv .venv
.venv\Scripts\activate

PyInstaller 설치

python -m pip install --upgrade pip
pip install pyinstaller

설치 확인:

pyinstaller --version

4) 가장 기본 빌드: onefile로 EXE 만들기

콘솔 프로그램(터미널 창 필요)

pyinstaller --onefile main.py

GUI 프로그램(창만 띄우고 콘솔 숨김)

pyinstaller --onefile --noconsole main.py

빌드가 끝나면 보통 아래 폴더가 생깁니다.

• dist/ : 실제 배포 파일(exe)
• build/ : 빌드 캐시
• main.spec : 빌드 설정 파일

결과 EXE는 dist/main.exe 에서 확인합니다.

5) 아이콘 넣기(윈도우 exe 느낌 살리기)

아이콘은 .ico 파일이 필요합니다. (png 그대로는 안됨)

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

6) 이미지/설정파일 등 “외부 파일” 포함하기

여기서 많이 막힙니다.
파이썬에서는 상대경로로 잘 읽히는데, exe로 묶이면 경로가 달라져요.

6-1) 빌드 옵션으로 파일 포함

예: assets/ 폴더를 함께 포함

pyinstaller --onefile --noconsole ^
  --add-data "assets;assets" ^
  main.py

윈도우에서 --add-data "원본;대상" 형태로 세미콜론(;)을 사용합니다.

6-2) exe 환경에서 경로 처리(핵심)

파이썬 코드에서 “실행 위치”를 잡는 함수를 넣어두면 안정적입니다.

import os, sysdef resource_path(relative_path: str) -> str:
    # PyInstaller로 묶이면 _MEIPASS 경로에 리소스가 풀림
    base_path = getattr(sys, "_MEIPASS", os.path.dirname(os.path.abspath(__file__)))
    return os.path.join(base_path, relative_path)

사용 예:

icon_path = resource_path("assets/app.ico")

7) “exe 실행하면 저장이 안돼요/초기화돼요” 문제 해결

이 현상은 거의 대부분 저장 위치가 잘못 잡혀서 생깁니다.

• 개발 중: 프로젝트 폴더에 저장
• exe 실행: 사용자 PC의 다른 위치에서 실행 → 상대경로가 달라짐
• 또는 Program Files 아래라면 쓰기 권한 문제로 저장 실패

추천: 사용자 폴더(AppData) 아래에 저장 폴더 만들기

import osdef get_app_data_dir(app_name="MyApp"):
    base = os.getenv("APPDATA")  # C:\Users\...\AppData\Roaming
    path = os.path.join(base, app_name)
    os.makedirs(path, exist_ok=True)
    return path

저장 예:

cfg_path = os.path.join(get_app_data_dir("HStockGuard"), "config.json")

이렇게 하면 exe로 배포해도 설정/저장 데이터가 유지됩니다.

8) 자주 겪는 에러/해결 체크리스트

✅ 실행하자마자 창이 꺼짐

• 콘솔 모드로 빌드해서 에러 확인
  --noconsole 빼고 실행해보기

✅ 모듈 못 찾는다고 나옴

• 누락된 모듈을 hidden-import로 추가

pyinstaller --onefile --hidden-import=패키지명 main.py

✅ 백신이 위험하다고 막음

• 새 exe는 오탐이 흔함
• 코드서명까지는 현실적으로 어렵고, 최소한 배포 파일을 자주 바꾸지 않는 게 도움
• 가능하면 onedir 배포도 고려(오탐이 덜 나는 경우가 있음)

✅ 용량이 너무 큼

• 가상환경을 깨끗하게 유지
• 불필요한 패키지 제거
• --exclude-module 사용 고려(상황에 따라)

9) 배포 방식 추천: onefile vs onedir

onefile

• 장점: 파일 1개로 배포 끝
• 단점: 실행 시 임시폴더에 풀리는 과정 때문에 첫 실행이 느릴 수 있음

onedir

pyinstaller --noconsole main.py

• 장점: 실행 빠르고 문제 추적이 쉬움
• 단점: 폴더째로 배포해야 함

개인적으로는 처음엔 onedir로 안정화 → 마지막에 onefile로 마무리하는 경우가 많았습니다.

FAQ

Q1. PyInstaller 말고 다른 방법도 있나요?
A. 네. cx_Freeze, Nuitka 같은 대안도 있습니다. 다만 가장 대중적이고 자료가 많은 건 PyInstaller입니다.

Q2. 32비트/64비트는 어떻게 맞추나요?
A. 빌드에 사용하는 파이썬이 64비트면 보통 64비트 exe가 됩니다. 배포 대상 PC 환경과 맞추세요.

Q3. exe로 만들면 소스가 완전히 숨겨지나요?
A. 완전한 보안은 아닙니다. “배포 편의” 목적에 가깝다고 보는 게 현실적입니다.

부록) 그대로 복사해서 쓰는 샘플 코드(저장 유지 + 리소스 경로)

core/paths.py

import os
import sysdef resource_path(relative_path: str) -> str:
    """
    PyInstaller(onefile)에서 리소스 경로를 안전하게 가져온다.
    """
    base_path = getattr(sys, "_MEIPASS", os.path.dirname(os.path.abspath(__file__)))
    return os.path.join(base_path, relative_path)def appdata_dir(app_name: str = "MyApp") -> str:
    """
    AppData\Roaming 아래에 앱 폴더를 생성해 저장 경로로 사용한다.
    """
    base = os.getenv("APPDATA") or os.path.expanduser("~")
    path = os.path.join(base, app_name)
    os.makedirs(path, exist_ok=True)
    return path

core/config.py

import json
import os
from .paths import appdata_dirdef load_config(app_name: str = "MyApp", filename: str = "config.json") -> dict:
    path = os.path.join(appdata_dir(app_name), filename)
    if not os.path.exists(path):
        return {}
    with open(path, "r", encoding="utf-8") as f:
        return json.load(f)def save_config(cfg: dict, app_name: str = "MyApp", filename: str = "config.json") -> str:
    path = os.path.join(appdata_dir(app_name), filename)
    with open(path, "w", encoding="utf-8") as f:
        json.dump(cfg, f, ensure_ascii=False, indent=2)
    return path

main.py (테스트용)

from core.config import load_config, save_configAPP_NAME = "HowinfoPyExeDemo"def main():
    cfg = load_config(APP_NAME)
    run_count = int(cfg.get("run_count", 0)) + 1
    cfg["run_count"] = run_count    saved_path = save_config(cfg, APP_NAME)
    print(f"[OK] 실행 횟수: {run_count}")
    print(f"[OK] 설정 저장 위치: {saved_path}")if __name__ == "__main__":
    main()

빌드 명령어(윈도우)

pyinstaller --onefile main.py

GUI + 아이콘 + assets 포함 예시:

pyinstaller --onefile --noconsole ^
  --icon=assets/app.ico ^
  --add-data "assets;assets" ^
  main.py

게시물 파이썬 프로그램을 윈도우 EXE로 만드는 방법 (PyInstaller 실전 가이드)이 하우인포-IT·테크에 처음 등장했습니다.

“개발을 잘 몰라도, AI와 대화만으로 설치형 프로그램을 만들 수 있을까?”

이번 프로젝트는 그 질문에서 시작했습니다.
목표는 단순하지만 분명했습니다.

Windows PC 바탕화면에서 항상 보이는 달력 + 일정 관리 프로그램
그리고 나중에 Android 앱과 연동 가능한 구조

웹앱이 아닌 완전한 설치형 프로그램으로요.

📌 프로젝트 목표 정리

이번 프로젝트의 핵심 목표는 아래 4가지였습니다.

• Windows 바탕화면에서 실행되는 독립형 캘린더 프로그램
• 날짜별 일정 추가 / 수정 / 삭제
• PC 재부팅 후에도 유지되는 로컬 데이터 저장
• 향후 Android 앱과 동기화 가능한 구조 설계

특히 중요한 조건은 하나였습니다.

❗ 코드는 직접 작성하지 않고, ‘바이브 코딩(자연어 + AI)’으로만 진행

🛠 사용한 기술 스택

왜 이 조합을 선택했을까?

이유는 단순합니다.

• Python은 비개발자도 진입 장벽이 낮고
• PyQt는 Windows 네이티브 느낌을 가장 잘 살릴 수 있으며
• SQLite는 서버 없이도 안정적인 데이터 저장이 가능하고
• PyInstaller로 단일 파일 배포가 가능하기 때문입니다.

🖥️ 1단계: Windows 데스크톱 캘린더 구현

가장 먼저 구현한 것은 기본 달력 UI입니다.

구현된 주요 기능

• 월별 달력 표시
• 오늘 날짜 강조
• 이전 / 다음 달 이동
• 날짜 클릭 시 일정 목록 표시

처음에는 “그냥 달력만 나오면 되겠지”라고 생각했지만,
막상 써보니 업무용으로는 부족했습니다.

그래서 바로 다음 단계로 넘어갔습니다.

📝 2단계: 일정 관리 기능 추가

업무용 캘린더의 핵심은 결국 일정 관리입니다.

추가한 기능은 다음과 같습니다.

• 일정 추가 / 수정 / 삭제
• 시간, 설명, 색상 지정
• 완료 여부 체크
• 날짜별 일정 자동 저장

이 모든 데이터는 SQLite 파일 하나로 관리됩니다.

👉 프로그램 폴더에 생성되는 .db 파일 하나만 백업하면
모든 일정이 그대로 복원됩니다.

💾 3단계: 로컬 저장 구조 설계 (중요)

이번 프로젝트에서 꽤 신경 쓴 부분입니다.

왜 로컬 저장을 먼저 선택했을까?

• 회사 PC 환경에서는 외부 서버 접근이 제한되는 경우가 많고
• 개인 업무 일정은 클라우드보다 로컬이 더 안전한 경우도 많기 때문입니다.

그래서 구조를 이렇게 잡았습니다.

[ UI (PyQt) ]
      ↓
[ Repository ]
      ↓
[ SQLite Database ]

이 구조 덕분에
👉 나중에 Firebase / REST API / Android 앱 연동을 붙이기도 쉽습니다.

⚠️ 예상치 못한 문제: 회사 SSL / 보안 환경

가장 큰 난관은 코드가 아니라 환경이었습니다.

발생한 문제

• 회사 네트워크에서 PyPI SSL 인증서 오류
• PyQt5, PyInstaller 설치 실패
• EXE 생성 단계에서 계속 중단

해결 방법

• --trusted-host 옵션 사용
• 미러 서버 활용
• 오프라인 wheel 파일 설치 가이드 제공

결국 회사 보안 환경에서도 설치 가능한 배치 파일 세트를 완성했습니다.

이 부분은 “실무 개발”에서 정말 중요한 경험이었습니다.

📦 4단계: 실행 파일 생성

최종 목표였던 독립 실행 파일도 완성했습니다.

실행 파일의 장점

• Python 설치 불필요
• 더블 클릭으로 실행
• 다른 PC로 복사해서 바로 사용 가능

생성 명령은 단순하지만,
앞선 SSL 문제를 해결하지 않으면 절대 여기까지 올 수 없었습니다.

📎 첨부 파일 안내

이 글과 함께 아래 파일들을 블로그에 첨부할 예정입니다.

📁 첨부 파일

• Python 전체 소스 코드
• 실행용 배치 파일
• EXE 생성용 스크립트
• 완성된 실행 파일 (DesktopCalendar)
• 사용 설명서 (README)

👉 코드를 몰라도

• 압축 해제
• 실행
• 바로 사용 가능하도록 구성했습니다.

✍️ 이번 프로젝트를 통해 느낀 점

이 프로젝트를 통해 확실히 느낀 점이 있습니다.

이제 “개발을 할 줄 아는 사람”과
“개발을 설계할 수 있는 사람”의 경계가 빠르게 무너지고 있다

코드를 직접 치지 않아도,

• 요구사항을 명확히 말할 수 있고
• 문제를 설명할 수 있고
• 결과를 검증할 수 있다면

👉 실제 제품 수준의 프로그램도 만들 수 있다는 걸 확인했습니다.

🔮 다음 단계 계획

다음 단계는 자연스럽게 이어집니다.

• Android 앱 버전 제작
• PC ↔ 모바일 일정 동기화
• 알림 기능 추가
• 반복 일정 / 태그 기능

이 역시 바이브 코딩 방식으로 계속 진행할 예정입니다.

마무리

이 글은 단순한 개발 튜토리얼이 아닙니다.

• “개발을 못 해도”
• “회사 환경이 빡세도”
• “시간이 많지 않아도”

👉 AI와 함께라면 어디까지 가능한지를 기록한 실제 사례입니다.

같은 방식으로 뭔가 만들어보고 싶다면,
이 프로젝트 기록이 작은 참고 자료가 되었으면 합니다.

[전체소스]

게시물 바이브 코딩으로 만든 Windows 바탕화면 캘린더 프로그램이 하우인포-IT·테크에 처음 등장했습니다.