파이썬 PyInstaller로 실행 파일 만들기 초보자도 5분 완성 가이드

파이썬으로 코딩을 하다 보면 이런 순간이 꼭 오더라고요. 내가 만든 멋진 프로그램을 친구나 동료에게 자랑하고 싶은데, 상대방 컴퓨터에 파이썬이 설치되어 있지 않아서 실행조차 못 하는 상황 말이에요. 소스 코드를 보내줘 봤자 “이거 어떻게 켜?”라는 질문만 돌아오고, 일일이 파이썬 설치부터 환경 변수 설정까지 설명하다 보면 진이 다 빠지죠. 저도 처음엔 이 과정이 너무 번거로워서 그냥 포기했던 적이 한두 번이 아니었거든요. 그런데 PyInstaller를 알고 나서는 이런 고민이 싹 사라졌습니다.

오늘은 제가 직접 겪은 시행착오를 바탕으로, 파이썬 스크립트(.py)를 누구나 더블 클릭 한 번으로 실행할 수 있는 실행 파일(.exe)로 만드는 방법을 아주 쉽게 풀어보려고 해요. 복잡한 이론보다는 당장 써먹을 수 있는 실전 팁 위주로 준비했으니 천천히 따라와 보세요.

PyInstaller 설치부터 시작하기

가장 먼저 해야 할 일은 당연히 라이브러리를 설치하는 거겠죠. 파이썬이 설치된 환경이라면 터미널이나 명령 프롬프트(CMD)에서 아주 간단한 명령어 하나면 끝납니다. 요즘은 개발 환경이 워낙 좋아져서 오류 나는 일도 거의 없더라고요.

pip install pyinstaller

엔터를 딱 치고 잠시 기다리면 설치가 완료됩니다. 가끔 권한 문제로 빨간 글씨가 뜰 때가 있는데, 그럴 땐 당황하지 말고 관리자 권한으로 터미널을 다시 열거나 명령어 앞에 sudo(맥이나 리눅스인 경우)를 붙여주면 해결되더라고요. 설치가 잘 됐는지 확인하고 싶다면 pyinstaller --version을 입력해보세요. 버전 숫자가 뜬다면 준비 완료입니다.

가장 기본적인 변환 방법

설치가 끝났으니 바로 변환을 해봐야겠죠? 바탕화면에 hello.py라는 파일이 있다고 가정해볼게요. 터미널에서 해당 파일이 있는 경로로 이동한 다음, 아래 명령어를 입력하면 됩니다.

pyinstaller hello.py

명령어를 실행하면 화면에 뭔가 주르륵 로그가 뜨면서 작업이 시작되는데요, 컴퓨터 사양에 따라 다르지만 보통 몇 초에서 1분 안에 끝납니다. 작업이 끝나면 폴더에 build와 dist라는 새 폴더가 생긴 걸 볼 수 있을 거예요. 여기서 중요한 건 dist 폴더입니다. 이 안에 들어가 보면 우리가 그토록 원하던 실행 파일이 들어있거든요.

근데 막상 들어가 보면 파일이 하나가 아니라 엄청나게 많은 파일들이 섞여 있을 거예요. 이게 기본 설정으로 빌드하면 실행에 필요한 라이브러리들을 폴더 형태로 묶어서 내보내기 때문이죠. 사실 배포할 때는 폴더째로 압축해서 줘야 하니까 좀 불편하더라고요.

깔끔하게 파일 하나로 만드는 꿀팁

그래서 제가 가장 애용하는 옵션들을 정리해 드릴게요. 저도 처음엔 그냥 기본 명령어로만 만들다가, 나중에는 이 옵션들 없이는 빌드를 안 하게 되더라고요. 특히 파일 하나로 뭉쳐주는 기능은 진짜 필수입니다.

아래 표에 자주 쓰는 핵심 옵션들을 정리해뒀으니, 필요할 때마다 참고해서 조합해 보세요.

예를 들어, 콘솔 창 없이 깔끔한 단일 실행 파일을 만들고 싶다면 이렇게 입력하면 되는 거죠.

pyinstaller -w -F hello.py

이렇게 하면 dist 폴더에 딱 파일 하나만 생성되니까 공유하기도 편하고 관리하기도 정말 좋습니다. 다만, 단일 파일 옵션(-F)을 쓰면 실행할 때 압축을 푸는 과정이 있어서 프로그램 시작 속도가 아주 조금 느려질 수 있다는 점은 감안해야 해요.

빌드 과정에서 자주 겪는 문제들

완벽하게 만들었다고 생각했는데 막상 실행해보면 에러가 나는 경우가 종종 있어요. 저도 이것 때문에 밤샌 적이 꽤 있는데요, 가장 흔한 문제는 바로 ‘경로’ 문제입니다. 파이썬 코드 안에서 이미지나 텍스트 파일을 불러올 때 절대 경로를 쓰면, 다른 사람 컴퓨터에서는 그 경로가 없으니까 당연히 에러가 나겠죠? 그래서 os.path 모듈을 사용해서 상대 경로로 코드를 짜는 습관을 들이는 게 정말 중요합니다.

그리고 또 하나, 용량 문제인데요. 간단한 코드인데도 실행 파일 용량이 300MB가 넘어가는 황당한 경우를 겪어보셨나요? 이건 아나콘다(Anaconda) 같은 통합 환경에서 빌드할 때 자주 발생해요. 불필요한 라이브러리까지 싹 다 끌어와서 패키징 해버리기 때문이죠. 이럴 땐 venv를 사용해서 딱 필요한 라이브러리만 설치된 가상 환경을 만들고, 거기서 PyInstaller를 돌리면 용량을 획기적으로 줄일 수 있습니다. 이거 진짜 꿀팁이니까 꼭 기억해 두세요.

마지막으로 바이러스 오진 문제입니다. 윈도우 디펜더나 백신 프로그램이 우리가 만든 exe 파일을 바이러스로 착각해서 삭제해 버리는 경우가 있어요. 이게 PyInstaller로 만든 파일들의 고질적인 문제 중 하나인데, 코드를 서명하거나 부트 로더를 다시 컴파일하는 복잡한 방법이 있긴 하지만, 개인적인 용도라면 백신 예외 설정을 하거나 지인에게 “바이러스 아니니까 안심해”라고 말해주는 게 정신 건강에 좋습니다.

마무리하며

사실 처음엔 좀 복잡해 보여도, 옵션 몇 개만 손에 익으면 파이썬 배포가 정말 쉬워집니다. 내가 만든 프로그램을 다른 사람들이 클릭 한 번으로 사용하는 모습을 보면 꽤 뿌듯하거든요. 오늘 알려드린 내용 바탕으로 여러분의 코드를 멋진 애플리케이션으로 재탄생시켜 보시길 바랍니다. 혹시 하다가 막히는 부분 있으면 너무 끙끙대지 말고 에러 메시지를 잘 읽어보세요. 대부분의 답은 그 안에 다 있더라고요.