[파이썬] exe파일로 만들기(pyinstaller)

I. pyinstaller 소개

파이썬은 간단하고 직관적인 문법으로 인해 다양한 분야에서 사용되고 있습니다. 하지만 파이썬은 실행 파일이 아닌 소스 코드 형태로 제공되기 때문에, 사용자는 파이썬 인터프리터를 미리 설치해야만 해당 코드를 실행할 수 있습니다. 이는 일반 사용자가 접근하기 쉽지 않은 점입니다.

이러한 문제를 해결하기 위해 pyinstaller가 개발되었습니다. pyinstaller는 파이썬 코드를 실행 파일 형태로 패키징하여 사용자가 별도의 파이썬 인터프리터 없이도 해당 프로그램을 실행할 수 있도록 합니다. 이를 통해 파이썬 프로그램의 배포와 실행이 쉬워져 파이썬을 이용한 소프트웨어 개발의 생산성을 높일 수 있습니다.

또한 pyinstaller는 다양한 운영체제와 환경에서 동작하는 실행 파일을 생성할 수 있으며, 데이터 파일과 같은 종속성을 포함시켜 실행 파일 하나로 모든 것을 해결할 수 있습니다. 이를 통해 배포 및 관리가 용이해지며, 효율적인 파이썬 프로그래밍이 가능합니다.

 

II. 설치

pyinstaller 설치 방법

pyinstaller는 pip을 통해서 설치할 수 있습니다.
windows, mac, linux에서 설치가 가능합니다.

pip install pyinstaller

필요한 패키지 설치?

pyinstaller를 사용하려면 프로그램에 필요한 라이브러리와 종속성이 설치되어야 합니다. pip으로 설치하게 되면 왠만한건 pyinstaller 설치시 탐지해서 설치해주지만 일부 패키지는 빠질 수도 있습니다. 이런 경우에 수동으로 패키지를 설치해주서야 합니다.
모듈이 없다는 오류가 나오면 하나씩 설치해주면 됩니다.

프로그램을 만들면 빌드 시스템에서 컴파일해야 하는 경우도 있는데 그러면 컴파일러와 빌드 도구도 필요할 수 있습니다. 상황에 맞게 하면 됩니다.

예외적인 경우가 있는데 pathlib 모듈이 깔려있으면 pyinstaller이 설치되지 않거나 실행되지 않습니다. 만약에 pathlib를 쓰고 있다면 새로운 가상환경을 만들어서 pyinstaller용 환경을 만드는 것을 추천합니다. pathlib 지우는데 한세월입니다.

III. 사용 방법

py파일에서 exe로 만드는 방법은 간단합니다.
터미널에서 다음을 입력하면 됩니다. 물론 해당 경로로 이동후 진행합니다.

pyinstaller 파일명.py

저 명령 하나면 알아서 빌드를 합니다.
그러면 dist와 build , main.spec가 생성됩니다.

실행파일은 dist 폴더에 py 파일명으로 된 폴더가 있는데 그 폴더에서 찾을 수 있습니다.

그런데 위의 코드대로 하면 exe 실행시키면 뒤에 콘솔창도 같이 나옵니다. 옵션을 붙여서 원하는 모양대로 만들어주어야 합니다.

설정 옵션

모든 옵션의 설명은 pyinstaller 홈페이지에서 볼 수 있습니다.

https://pyinstaller.org/en/stable/usage.html

Using PyInstaller — PyInstaller 5.10.1 documentation

저는 몇가지 유용한 옵션들만 설명하겠습니다.
나머지는 홈페이지에서 살펴보시길 바랍니다.

콘솔창 출력되지 않도록 하기

콘솔창을 활용하는 분들도 있지만 대개는 필요하지 않을 겁니다.
안나오는게 깔끔하죠. 콘솔창이 출력되지 않게 하려면 -w 또는 --windowed 를 옵션에 추가합니다.

pyinstaller -w 파일명.py

exe파일 하나만 생성하기

실행파일 하나만 생성할 수 있습니다. 다만, 실행파일 하나에 모든 걸 다 몰아넣었기 때문에 실행시작시간이 길어집니다.
나는 프로그램을 실행시키면 20~30초후에야 프로그램이 뜹니다.
큰 스케일의 프로그램이면 더 오래걸립니다. 간단한 프로그램 만들었을 때 주로 씁니다.

pyinstaller -F 파일명.py

이름 지정

변환될 이름을 미리 지정합니다. 이 옵션을 쓰지 않으면 py이름을 따라갑니다.

pyinstaller -n NewName.exe 파일명.py

아이콘 설정

프로그램에 아이콘을 설정하는 방법입니다. 윈도우인 경우는 아이콘 따로 설정할 수 있어서 굳이 긴 명령어를 칠 필요는 없지만 다른 운영체제는 그렇지 않기 때문에 알아두면 좋습니다. 참고로 탐색창에서 보여지는 아이콘만 설정됩니다.

pyinstaller --icon=icon.ico 파일명.py

아이콘 파일도 스크립트와 같은 폴더에 있어야 합니다. 경로를 하려고 했더니 될때도 있긴 한데 잘 안 되더군요.

debug 모드로 프로그램 만들기

모든 빌드가 온전히 되었는지 확인하기 위해서 디버그 모드로 만듭니다. 오류를 확인하기 위해 cmd 창이 같이 뜨는 건 감안하고 만드는 모드입니다. 배포를 한다면 여러 환경에서도 돌아가는지 확인해야하는데 그러기 위해서 어디서 오류가 나왔는지 알아야 하기 때문에 확인차 사용합니다. -d 또는 -debug를 사용합니다.

pyinstaller -d 파일명.py

그런데 pyinstaller 자체가 불안정하면 디버그모드든 뭐든 그냥 꺼집니다. 화면이 시작되다가 중지되는데 그럴 때는 디버그모드도 안됩니다. 개발환경에 문제가 있을수 있고 py 자체에 문제가 있을수도 있습니다. 이런 경우는 윈도우인 경우 작업 스케쥴러를 활용해서 py가 안되는 이유를 하나씩 찾아가면 됩니다.
자세한 사항은 아래 포스팅을 참고해주시기 바랍니다.

 

작업 스케쥴러에서 파이썬 실행 안될때 오류 보기

 

예시

옵션을 다 사용하려면 옵션을 하나씩 추가하면 됩니다.
만약 콘솔창 없애기, 한파일로 만들기, 실행파일 이름 바꾸기를 덧붙인다고 하면 다음과 같이 합니다.

pyinstaller -w -F -n Newname.exe 파일명.py

 

옵션이 이밖에도 많은데 대체로 복잡합니다. 이런 옵션을 Auto-py-to-exe라고 해서 GUI 프로그램으로 만든 사례가 있는데 참고하시기 바랍니다. 이 프로그램은 오류가 많아서 저는 안 쓰고 있는데 그게 몇년 전이라서 지금은 많이 개선됐을 수도 있습니다. 제일 좋은 건 터미널에서 명령 하는게 제일 좋긴 하지만 너무 어렵다 싶으면 먼저 프로그램을 사용하면서 익히는것도 괜찮을 것 같습니다.

 

[Python] py파일 exe로 만들기(Auto-py-to-exe)

 

IV. 자주 나타나는 오류

실행 파일이 작동하지 않는 경우

pyinstaller로 생성한 실행 파일이 정상적으로 작동하지 않는 경우가 있습니다. 이 경우, 대부분의 경우 실행 파일이 필요로 하는 파일이나 라이브러리가 빠져 있어서 발생하는 문제입니다.

이 경우, 실행 파일을 생성할 때 -D 옵션을 사용하여 실행 파일과 함께 필요한 파일들을 함께 배포하면 됩니다. -D 옵션은 --onedir 옵션으로 대체하여 사용할 수도 있습니다.

pyinstaller -D 파일명.py

-D 로 해결되면 좋겠지만 그렇지 않으면 골치아파집니다. 오류를 직접 찾아가야합니다. py파일에 오류가 있으면 해결하면 그만이지만 그렇지 않으면 버전문제일 수 있습니다.
버전 문제인 경우는 해당 가상환경의 패키지 업그레이드를 합니다. 특히, numpy, pandas는 pyinstaller 필수 패키지라서 업데이트가 되어있어야 합니다.
패키지 모듈 업그레이드 방법은 다음 포스팅에서 확인하시기 바랍니다.

 

[Python] pip 패키지 설치제거, 버전 업그레이드

소문에는 파이썬 3.10 이상인 경우는 pyinstaller로 빌드가 잘 안된다고 하니 왠만하면 파이썬 3.9 버전으로 pyinstaller를 하는게 안전합니다.

 

실행 파일 크기가 너무 큰 경우

pyinstaller로 생성된 실행 파일의 크기가 너무 커서 배포에 어려움을 느끼는 경우가 있습니다. 이 경우, 실행 파일에서 사용하지 않는 라이브러리나 파일들을 제거하여 크기를 줄일 수 있습니다.

먼저, 실행 파일에서 사용되는 라이브러리와 파일들을 확인합니다.

pyinstaller [파일명.py] --debug all --log-level DEBUG

위 명령어를 실행하면, 실행 파일에서 사용되는 모든 라이브러리와 파일들이 출력됩니다. 이 중에서 사용하지 않는 라이브러리와 파일들을 제거합니다.

pyinstaller 파일명.py --exclude-module 제외할모듈명 --exclude 제외할파일명

위 명령어를 실행하면, 지정한 모듈과 파일을 제외하여 실행 파일을 생성합니다.

 

오류 메시지가 발생하는 경우

pyinstaller로 생성된 실행 파일을 실행하다가 오류 메시지가 발생하는 경우가 있습니다. 이 경우, 실행 파일이 필요로 하는 라이브러리나 파일들이 올바르게 포함되지 않았을 가능성이 있습니다.

이 경우, -hidden-import 옵션을 사용하여 필요한 라이브러리를 추가해보거나, --add-data 옵션을 사용하여 필요한 파일을 함께 묶어서 배포합니다.

# 라이브러리 추가
pyinstaller --hidden -import 패키지명 파일명.py

# 필요한 파일 추가
pyinstaller --add-data="리소스경로; 실행경로" 파일명.py

윈도우 환경에서는 세미콜론(;)을 하고 유닉스에서는 콜론(:)으로 구분해야 합니다.

예를 들어 같은 폴더에 있는 adc.exe를 추가한다고 하면 다음과 같이 씁니다.

pyinstaller --add-data="abc.exe"; ./" 파일명.py

V. 마치며

이상으로 pyinstaller에 대한 설치, 사용 방법, 그리고 문제 해결 방법들을 알아보았습니다. pyinstaller를 사용하면 파이썬 프로그램을 쉽게 실행 파일로 변환하여 배포할 수 있습니다. 
pyinstaller 외에도 cx_Freeze, py2exe, PyOxidizer 등 파이썬 프로그램을 실행 파일로 변환해주는 도구들이 있으니 참고하시기 바랍니다.

 

함께 보면 좋은 글

[Python] pip 패키지 설치제거, 버전 업그레이드

[Anaconda]가상환경 설치,삭제(32bit 포함)

작업 스케쥴러에서 파이썬 실행 안될때 오류 보기

[Python] py파일 exe로 만들기(Auto-py-to-exe)