PyQt5 설치 및 기본 설정 가이드

✅ PyQt5 설치 및 기본 설정 가이드

PyQt5는 Python에서 GUI(Graphical User Interface)를 만들 수 있도록 도와주는 라이브러리입니다.
PyQt는 Qt 프레임워크를 기반으로 하며, 윈도우, macOS, 리눅스에서 GUI 애플리케이션을 개발하는 데 사용할 수 있습니다.

---

✅ 1. PyQt5 설치하기

PyQt5를 설치하기 전에 Python과 pip가 정상적으로 설정되어 있는지 확인하세요.

🔹 1) Python과 pip 확인

CMD(명령 프롬프트) 또는 터미널에서 아래 명령어를 실행합니다.

python --version
pip --version

정상적으로 버전 정보가 출력되면 설치를 진행할 수 있습니다.

🔹 2) PyQt5 설치

PyQt5는 pip를 사용하여 쉽게 설치할 수 있습니다.

pip install PyQt5

또는 디자이너(Qt Designer) 및 기타 유틸리티 포함 패키지를 함께 설치하려면:

pip install PyQt5 PyQt5-tools

설치가 완료되면 다음 명령어로 설치된 패키지를 확인하세요.

pip list | findstr PyQt5

또는

pip show PyQt5

설치된 버전이 출력되면 정상적으로 설치된 것입니다. 🎉

---

✅ 2. PyQt5 기본 GUI 코드 실행

설치가 잘 되었는지 확인하려면 간단한 GUI 창을 띄워보겠습니다.

import sys
from PyQt5.QtWidgets import QApplication, QLabel, QWidget

app = QApplication(sys.argv)

# 창 생성
window = QWidget()
window.setWindowTitle("PyQt5 기본 예제")
window.setGeometry(100, 100, 400, 300)  # (x, y, width, height)

# 라벨 추가
label = QLabel("Hello, PyQt5!", window)
label.move(150, 130)

window.show()

sys.exit(app.exec_())

✅ 설명

• QApplication: PyQt 애플리케이션을 실행하는 핵심 객체
• QWidget: GUI 창을 생성하는 기본적인 위젯
• QLabel: 텍스트 라벨을 추가하는 위젯
• setGeometry(x, y, width, height): 창의 위치와 크기 설정
• show(): GUI 창을 표시
• sys.exit(app.exec_()): 애플리케이션 실행

✅ 실행 방법

1. 위 코드를 pyqt_test.py로 저장
2. 터미널에서 실행

   python pyqt_test.py
   

3. PyQt5 GUI 창이 정상적으로 나타나는지 확인합니다.

---

✅ 3. PyQt Designer 설치 및 실행 (GUI 디자인 툴)

PyQt5에서 GUI를 직접 디자인하려면 Qt Designer를 사용할 수 있습니다.

🔹 1) Qt Designer 실행 (PyQt5-tools 설치 후)

PyQt5-tools가 설치되었다면, 아래 경로에서 실행 파일을 찾을 수 있습니다.

python -m PyQt5.tools.designer

또는 설치된 경로에서 직접 실행 (경로는 시스템마다 다를 수 있음)

C:\Users\사용자이름\AppData\Local\Programs\Python\PythonXX\Lib\site-packages\pyqt5_tools\designer.exe

🔹 2) Qt Designer에서 .ui 파일 만들기

1. Qt Designer 실행
2. 새로운 창 레이아웃 선택 (예: Main Window)
3. 버튼, 텍스트 필드 등 원하는 UI 구성 요소 추가
4. 파일 → 저장 (.ui 파일로 저장)

🔹 3) .ui 파일을 PyQt5 코드로 변환

pyuic5 -x design.ui -o design.py

이렇게 하면 .ui 파일이 Python 코드(design.py)로 변환됩니다.

---

✅ 4. PyQt5 프로젝트 시작하기

PyQt5를 이용해 GUI 프로젝트를 개발할 때는 다음과 같은 구조를 추천합니다.

/my_pyqt_app
    ├── main.py      # 실행 파일
    ├── design.ui    # Qt Designer에서 만든 UI 파일
    ├── design.py    # 변환된 UI 코드
    ├── resources.qrc # 리소스 파일 (이미지, 아이콘 등)
    ├── resources_rc.py # 변환된 리소스 파일
    ├── assets/      # 이미지, 아이콘 저장 폴더

---

✅ 5. PyQt5 실행 중 발생할 수 있는 오류 해결

🔹 1) qt.qpa.plugin: Could not find the Qt platform plugin "windows"

이 오류가 발생하면 아래 명령어를 실행하여 PyQt5를 재설치합니다.

pip uninstall PyQt5 PyQt5-tools
pip install PyQt5 PyQt5-tools

🔹 2) ModuleNotFoundError: No module named 'PyQt5'

Python의 가상환경(venv)을 사용할 경우, pip install PyQt5를 실행한 환경이 올바른지 확인하세요.

python -m venv venv
source venv/bin/activate  # (Mac/Linux)
venv\Scripts\activate  # (Windows)
pip install PyQt5

---

🎯 정리

✅ PyQt5 설치 ✅ 간단한 GUI 프로그램 실행 ✅ Qt Designer로 UI 디자인 ✅ .ui 파일을 Python 코드로 변환
✅ PyQt5 프로젝트 구조 추천

PyQt5를 사용하면 GUI 기반의 Python 프로그램을 쉽게 만들 수 있습니다! 🚀