업무 자동화 도구를 만들 때 기술보다 어려운 것이 배포입니다. 사용자는 개발자가 아닙니다. "파이썬을 설치하고, 가상환경을 만들고, pip install을 실행하세요"라고 안내하는 순간 그 도구는 안 쓰이게 됩니다. 카페24 셀러용 재고 변환 프로그램을 납품하며 우리가 잡은 기준은 하나였습니다. 받은 파일을 더블클릭하면 바로 화면이 뜬다. 이 글은 그 기준을 만족시킨 파이썬 EXE 배포 설계를 정리했습니다.
파이썬 EXE는 단일 실행 파일로
배포 형태의 선택지는 여러 가지입니다. 설치 프로그램(인스톨러), 폴더째 전달, 단일 실행 파일. 비개발자 사용자에게는 단일 실행 파일이 압도적으로 낫습니다. 받아서 더블클릭, 끝. 설치 권한 문제도, "어떤 파일을 실행해야 하나요" 문의도 없습니다.
우리는 PyInstaller의 단일 파일(one-file) 모드로 빌드했습니다. 파이썬 런타임과 라이브러리가 실행 파일 하나에 담기므로 사용자 PC에 아무것도 설치할 필요가 없습니다. 대신 파일 크기와 첫 실행 속도가 대가이므로, 의존성 관리가 중요해집니다.
의존성 다이어트: pandas를 빼는 결정
단일 파일 빌드에서 실행 파일 크기는 의존성의 합입니다. 처음에는 엑셀 처리에 pandas를 썼는데, 데이터 분석 없이 셀을 읽고 쓰는 용도로는 과했습니다. pandas와 그 뒤에 딸려 오는 numpy가 실행 파일을 크게 불리기 때문입니다. 그래서 엑셀 엔진을 openpyxl 하나로 통일하고 pandas 의존성을 제거했습니다.
이 결정의 기준은 단순합니다. 라이브러리가 제공하는 기능 중 실제로 쓰는 것이 무엇인가. 셀 단위 읽기·쓰기라면 openpyxl로 충분하고 표 연산이 필요해지면 그때 다시 판단하면 됩니다. 배포형 도구에서 의존성 하나는 기능이 아니라 비용입니다.
더블클릭하면 GUI, 인자를 주면 CLI
같은 프로그램을 두 방식으로 쓸 수 있게 진입점을 설계했습니다. 인자 없이 실행(더블클릭)하면 GUI가 뜨고 명령줄 인자를 주면 CLI로 동작합니다. 일반 사용자는 화면으로 쓰고 예약 실행이나 다른 시스템과의 연동이 필요하면 명령줄로 자동화할 수 있습니다.
명령줄 쪽은 세 개의 하위 명령(단일 변환, 일괄 변환, GUI 실행)으로 정리해 자동화 스크립트에서 특정 작업만 골라 부를 수 있게 했습니다. GUI와 CLI가 같은 코어 로직을 쓰므로 어느 쪽으로 실행해도 결과는 동일합니다.
윈도우에서는 한 가지 디테일이 더 있습니다. GUI 프로그램인데 콘솔 창이 같이 뜨면 사용자는 "까만 창"에 불안해합니다. 진입점에서 실행 맥락을 판단해 GUI 모드일 때는 콘솔이 나타나지 않게 처리했습니다. 사소해 보여도 비개발자 사용자의 신뢰에는 이런 디테일이 큽니다.
빌드는 CI가 한다
납품형 도구의 함정은 "빌드가 개발자 PC에서만 된다"는 상태입니다. 수정 요청이 몇 달 뒤에 오면 빌드 환경부터 복구해야 합니다. 우리는 GitHub Actions에 윈도우 러너로 빌드 워크플로를 만들어 코드를 밀면 테스트가 돌고 EXE가 릴리스 자산으로 만들어지게 했습니다. 맥용 실행 파일은 별도 빌드 스크립트로 같은 코드에서 나옵니다.
맥용 빌드 스크립트도 저장소에 함께 두어 두 플랫폼의 빌드가 모두 코드에서 재현됩니다.
CI 빌드의 진짜 가치는 재현성입니다. 어느 커밋에서든 같은 절차로 같은 산출물이 나오므로, "지난번 납품본이 어떤 코드였지"라는 질문에 커밋과 릴리스가 답합니다. 빌드 전에 파이썬 테스트가 매번 실행되어 로직 회귀가 실행 파일에 실려 나가는 것도 막아 줍니다.
| 설계 항목 | 선택 | 이유 |
|---|---|---|
| 배포 형태 | 단일 실행 파일 | 설치 없음 · 더블클릭 실행 |
| 엑셀 엔진 | openpyxl 단독 | pandas 제거로 파일 경량화 |
| 진입점 | 무인자 GUI · 인자 CLI | 일반 사용자와 자동화 양쪽 지원 |
| 빌드 | CI 자동 빌드 + 테스트 | 재현성 · 회귀 차단 |
이 배포 설계가 적용된 도구의 전체 이야기는 카페24 재고 업로드 자동화에서 볼 수 있습니다. 도구 내부의 로직을 어떻게 기존 엑셀 업무에서 옮겨 왔는지는 VLOOKUP 업무 자동화에서, 납품 후에도 유지되는 코드 구조는 인수인계 가능한 코드를 만드는 법에서 다룹니다.
자주 묻는 질문
파이썬 프로그램을 EXE로 만들면 사용자가 파이썬을 설치해야 하나요?
아니요. 단일 실행 파일 빌드는 파이썬 런타임과 필요한 라이브러리를 실행 파일 안에 포함하므로, 사용자 PC에는 아무것도 설치할 필요가 없습니다. 받아서 더블클릭하면 바로 실행됩니다.
EXE 파일이 너무 커지는데 어떻게 줄이나요?
의존성을 줄이는 것이 가장 효과적입니다. 실제로 쓰는 기능이 셀 읽기·쓰기 수준이라면 pandas 같은 무거운 라이브러리 대신 가벼운 전용 라이브러리로 대체하는 식입니다. 배포형 도구에서 의존성은 기능이 아니라 크기와 실행 속도의 비용으로 계산해야 합니다.
맥과 윈도우를 같이 지원할 수 있나요?
같은 코드에서 플랫폼별로 빌드하면 됩니다. 다만 실행 파일은 빌드한 운영체제에서만 동작하므로, 윈도우용은 윈도우 환경에서, 맥용은 맥 환경에서 각각 빌드해야 합니다. CI의 플랫폼별 러너를 쓰면 이 과정을 자동화할 수 있습니다.
수정 요청이 오면 빌드를 다시 해야 하는데 번거롭지 않나요?
CI에 빌드를 맡기면 번거로움이 사라집니다. 코드를 수정해 밀면 테스트가 돌고 실행 파일이 자동으로 만들어지므로, 몇 달 뒤의 수정 요청에도 빌드 환경 복구 없이 바로 대응할 수 있습니다.