파이썬으로 코딩한 후 이를 간편하게 사용하기 위해서는 그래픽 인터페이스를 제공하는 방법이 콘솔을 통해 명령어를 입력하는 방식보다 훨씬 편리합니다. 그러나 그래픽 인터페이스와 다양한 기능을 결합한 애플리케이션을 개발하는 과정은 초보자에게 벅차게 느껴질 수 있습니다.
그럼에도 불구하고, PySide6를 사용하면 Qt 프레임워크의 강력한 기능을 파이썬에서 사용할 수 있어, 웹 기술과 네이티브 기능을 결합한 하이브리드 애플리케이션 개발이 가능합니다.
많은 개발자들이 애플리케이션 개발을 마친 후, 배포 단계에서 PyInstaller로 패키징한 실행 파일이 제대로 작동하지 않는 경우가 발생합니다. 특히 QtWebEngine을 사용하는 경우, 문제들이 자주 발생합니다:
PyInstaller-PySide6-컴파일-과정-문제-해결방법
- QtWebEngine 관련 파일 누락
- 리소스 파일 부재
- 런타임 의존성 문제
이 글에서는 PyInstaller를 활용한 PySide6 웹뷰 애플리케이션 컴파일 방법을 단계별로 설명합니다.
1. 필수 준비물
애플리케이션을 패키징하기 전에 필요한 준비물을 설치해야 합니다:
- Python 3.7 이상: 최신 버전의 파이썬을 설치해야 합니다.
- PySide6:
pip install pyside6명령어로 PySide6를 설치합니다. - PyInstaller:
pip install pyinstaller명령어로 PyInstaller를 설치합니다. - 10GB 이상의 여유 디스크 공간: 패키징 과정에서 많은 파일이 생성되므로, 충분한 디스크 공간이 필요합니다.
이 준비물을 모두 갖춘 후, 본격적인 컴파일 작업에 들어갈 수 있습니다.
2. 기본 컴파일 명령어 (실패하는 경우)
PyInstaller를 사용하여 PySide6 애플리케이션을 컴파일하는 기본적인 명령어는 다음과 같습니다:
pyinstaller --onefile --noconsole ex.py
하지만 이 명령어는 종종 실패할 수 있습니다. 실패하는 주된 원인은 다음과 같습니다:
- QtWebEngineProcess.exe 누락: QtWebEngine 관련 웹 콘텐츠 렌더링이 불가해지며, 이는 애플리케이션이 정상적으로 작동하지 않게 만듭니다.
- 리소스 파일 부재: 아이콘, 폰트 등의 UI 리소스가 빠지면 애플리케이션이 불완전하게 실행됩니다.
- 런타임 의존성 문제: Qt 플러그인 로드 실패로 애플리케이션 실행 중 오류가 발생할 수 있습니다.
이러한 문제를 해결하기 위한 방법을 아래에서 단계별로 설명합니다.
실패 원인 분석
- QtWebEngineProcess.exe 누락: 웹 콘텐츠 렌더링 불가
- 리소스 파일 부재: 아이콘, 폰트 등 UI 리소스 없음
- 런타임 의존성 문제: Qt 플러그인 로드 실패
3. 완벽한 컴파일 하기
PyInstaller를 사용할 때 QtWebEngine 관련 파일을 명시적으로 추가해야 합니다. 이를 위해 아래와 같은 명령어를 사용합니다。
3.1. 수동 명령어 방식 (Windows)
pyinstaller --onefile --noconsole ^
--add-data "C:path oPythonLibsite-packagesPySide6QtinQtWebEngineProcess.exe;QtWebEngineProcess" ^
--add-data "C:path oPythonLibsite-packagesPySide6Qt
esources;Qt
esources" ^
--add-data "C:path oPythonLibsite-packagesPySide6Qt ranslations;Qt ranslations" ^
ex.py
PyInstaller를 사용할 때 QtWebEngine 관련 파일을 명시적으로 추가해야 합니다.
3.2. 자동화 스크립트 방식 (추천)
위와 같은 수동 방식이 번거롭다면, 자동화 스크립트를 작성하여 컴파일을 간편하게 처리할 수 있습니다. 아래는 이를 위한 자동화 스크립트 build.py의 예시입니다. ‘ex.py’는 PyInstaller로 패키징할 파이썬 스크립트 파일의 이름입니다. 기타 설정은 자동으로 설치 경로를 지정하지만, 간혹 설치 경로가 변경될 수 있습니다.
수정해야 할 부분은 여기서, 실제 빌드하려는 Python 파일의 이름으로 수정해야 합니다. 예를 들어, 파일 이름이 main.py로 다르다면 ‘main.py’를 변경해야 합니다. 그리고 컴파일될 파일 이름 정도만 변경해서 사용하시면 됩니다.
import os
import site
from PyInstaller.__main__ import run
# PySide6 설치 경로를 찾습니다.
pyside6_dir = site.getsitepackages()[0] + "\PySide6"
opts = [
'ex.py', # 빌드할 파이썬 스크립트 파일
'--onefile', # 하나의 실행 파일로 만듭니다.
'--noconsole', # 콘솔 창을 표시하지 않도록 설정합니다.
'--add-data', f'{pyside6_dir}\Qt\bin\QtWebEngineProcess.exe;QtWebEngineProcess',
'--add-data', f'{pyside6_dir}\Qt\resources;Qt\resources',
'--add-data', f'{pyside6_dir}\Qt\translations;Qt\translations',
'--name', 'MyWebViewApp' # 생성할 실행 파일의 이름 설정
]
# PyInstaller 실행
run(opts)
이렇게 하면 PyInstaller 명령어를 매번 입력하는 번거로움 없이 자동으로 컴파일을 처리할 수 있습니다.
build.py
0.00MB
python build.py
4. 컴파일 후 검증 방법
- 파일 구조 검사: QtWebEngineProcess 및 리소스 폴더 확인
- 실행 테스트: 관리자 권한 없이 일반 모드로 실행
- 디버깅: 콘솔 로그 확인 (–noconsole 옵션 제거 후)
5. 배포 방법
- 인스톨러 패키징: Inno Setup 또는 NSIS 사용
- 코드 서명: Windows 스마트스크린 경고 방지
- 업데이트 메커니즘: 자동 업데이트 기능 구현
6. 문제 해결 방법
Q1. ‘QtWebEngineProcess not found’ 오류 해결법
PySide6 설치 경로를 정확히 확인하세요. 가상 환경 사용 시 다음 명령어로 위치 확인:
python -c "import PySide6; print(PySide6.__file__)"
Q2. exe 실행 시 흰 화면 문제
QtWebEngineProcess.exe와 리소스 파일이 제대로 포함되었는지 확인
Q3. 파일 크기 줄이는 방법
UPX 압축 도구 사용: --upx-dir 옵션 추가
7. 배포를 위한 체크포인트
- 모든 리소스 파일 포함 확인
- 다양한 Windows 버전(10, 11)에서 테스트
- 바이러스 검사 수행
- 사용자 매뉴얼 작성