PyInstaller로 파이썬 실행파일 만들기 및 에러 해결

파이썬(Python)은 배우기 쉬운 문법과 강력한 기능 덕분에 데이터 분석, 웹 개발, 머신러닝 등 다양한 분야에서 널리 사용되고 있는 언어입니다. 하지만 파이썬 코드를 다른 사람과 공유하거나, 파이썬이 설치되지 않은 환경에서 실행해야 할 때 어려움을 겪을 수 있습니다. 이때 파이썬 코드를 실행 파일(.exe)로 변환해주는 기능이 필요합니다. 이 글에서는 PyInstaller를 사용하여 파이썬 실행 파일을 만드는 방법과, 흔히 발생하는 에러들을 해결하는 방법을 알아보도록 하겠습니다.

파이썬 코드 실행 파일 배포 장점

1) 파이썬 설치 없이 실행:파이썬 인터프리터가 설치되지 않은 환경에서도 실행 파일을 실행할 수 있습니다.

2) 코드 보호:파이썬 코드를 직접 배포하는 대신 실행 파일을 배포하여 코드 유출을 방지할 수 있습니다.

3) 편리한 배포:복잡한 의존성 관리 없이, 실행 파일 하나만으로 프로그램을 배포할 수 있습니다.

4) 사용자 친화적인 인터페이스: GUI 프로그램을 실행 파일로 만들어 사용자에게 편리한 사용 환경을 제공할 수 있습니다.

PyInstaller 설치 

PyInstaller를 설치하는 것은 매우 간단합니다. 윈도우(Windows), macOS, 리눅스(Linux) 등 어떤 운영체제를 사용하든,pip이라는 파이썬 패키지 관리자를 통해 쉽게 설치할 수 있습니다.

 

1) 명령 프롬프트 또는 터미널 열기

• 윈도우에서는 cmd를 검색하여 명령 프롬프트를 열고, macOS나 리눅스에서는 터미널 애플리케이션을 실행합니다.

2) PyInstaller 설치 명령어 입력 

• 다음 명령어를 입력하고 Enter 키를 누릅니다.만약 "pip" 명령어를 찾을 수 없다는 오류가 발생하면, 파이썬 설치 시 "Add Python to PATH" 옵션을 선택했는지 확인하거나, pip를 수동으로 설치해야 합니다.
• pip install pyinstaller

3) 설치 확인

• PyInstaller가 제대로 설치되었는지 확인하려면 다음 명령어를 입력합니다. PyInstaller 버전 정보가 출력되면 정상적으로 설치된 것입니다.
• pyinstaller --version

파이썬 실행 파일 만들기 

PyInstaller 설치가 완료되었다면, 이제 파이썬 코드를 실행 파일로 변환할 차례입니다. PyInstaller는 다양한 옵션을 제공하지만, 가장 기본적인 명령어만으로도 충분히 실행 파일을 만들 수 있습니다.

 

1) 실행 파일로 만들 파이썬 파일 준비

• 실행 파일로 만들 파이썬 파일(.py)을 준비합니다. 예시로 test.py라는 이름의 파이썬 파일을 만들었습니다.

2) PyInstaller 실행 명령어 입력

• 명령 프롬프트 또는 터미널에서 파이썬 파일이 있는 디렉토리로 이동한 후, 다음 명령어를 입력합니다. --onefile옵션은 모든 의존성 파일을 하나의 실행 파일로 묶어줍니다. 이 옵션을 사용하면 배포가 훨씬 간편해집니다.
• pyinstaller --onefile test.py

3) 실행 파일 확인

• 실행 파일 생성 과정이 완료되면, dist 폴더 안에 실행 파일(test.exe)이 생성됩니다.

PyInstaller 옵션 정리

PyInstaller는 다양한 옵션을 제공합니다. 몇 가지 유용한 옵션입니다.

• --name <name>:실행 파일의 이름을 지정합니다. 예를 들어, --name my_app 옵션을 사용하면 실행 파일 이름이 my_app.exe로 변경됩니다.
• --noconsole:콘솔 창을 숨깁니다. GUI 프로그램의 경우 콘솔 창이 필요 없으므로 이 옵션을 사용하는 것이 좋습니다.
• --icon <icon_file.ico>:실행 파일의 아이콘을 변경합니다. 보기 좋은 아이콘을 사용하면 프로그램의 완성도를 높일 수 있습니다. 아이콘 파일은 .ico 형식이어야 합니다.
• --add-data <source:dest>:파이썬 스크립트와 함께 포함해야 하는 데이터 파일을 지정합니다. 예를 들어, 이미지 파일이나 설정 파일을 함께 묶을 수 있습니다.
• --windowed:윈도우 GUI 어플리케이션으로 실행 파일을 만들 때 사용합니다. 콘솔 창이 나타나지 않습니다.

사용 예시:

 pyinstaller --onefile --noconsole --icon test_icon.ico test.py

이 명령어는 test.py를 실행 파일로 만들면서, 콘솔 창을 숨기고 test_icon.ico 파일을 아이콘으로 사용합니다.

에러 해결 방법

PyInstaller를 사용하다 보면 다양한 에러를 만날 수 있습니다. 주로 발생하는 에러와 해결 방법입니다.

• "ModuleNotFoundError: No module named 'xxx'" 오류:
  • 원인:필요한 파이썬 모듈이 설치되지 않았거나, PyInstaller가 모듈을 제대로 찾지 못하는 경우 발생합니다.
  • 해결 방법:
    • 해당 모듈이 설치되어 있는지 확인합니다. 설치되어 있지 않다면 pip install xxx 명령어로 설치합니다.
    • PyInstaller 실행 시 --hidden-import xxx 옵션을 사용하여 해당 모듈을 명시적으로 지정합니다.
• "Failed to execute script 'xxx'" 오류:
  • 원인:실행 파일 실행 중 예외가 발생한 경우 발생합니다.
  • 해결 방법:
    • 터미널에서 실행 파일을 실행하여 오류 메시지를 확인하고, 파이썬 코드의 버그를 수정합니다.
    • --debug 옵션을 사용하여 디버깅 모드로 실행 파일을 만들고, 오류 발생 지점을 찾습니다.
• "'pyinstaller'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다." 오류:
  • 원인:PyInstaller가 설치되었지만, 시스템 환경 변수에 등록되지 않아 명령어를 인식하지 못하는 경우 발생합니다.
  • 해결 방법:
    1. PyInstaller 설치 경로 확인:pip show pyinstaller 명령어를 통해 PyInstaller가 설치된 경로를 확인합니다.
    2. 환경 변수 편집:
       • 윈도우 검색창에서 "환경 변수 편집"을 검색하여 시스템 속성 창을 엽니다.
       • "환경 변수" 버튼을 클릭하고, "시스템 변수" 목록에서 "Path" 변수를 찾아 "편집" 버튼을 클릭합니다.
       • "새로 만들기" 버튼을 클릭하고, PyInstaller가 설치된 경로를 추가합니다.
       • 모든 창을 닫고 컴퓨터를 재부팅합니다.

맺음말

PyInstaller를 사용하여 파이썬 실행 파일을 만드는 방법과, 흔히 발생하는 오류들을 해결하는 방법을 자세하게 알아보았습니다. PyInstaller로 파이썬 코드를 실행 파일로 만들고, 다른 사람들과 편리하게 공유할 수 있습니다. 자신만의 멋진 파이썬 프로그램을 만들어 공유해보세요.