Pythonで始めるPyQt/PySide: 高機能デスクトップアプリの作り方

2025年9月17日

Python

Pythonで高機能なデスクトップアプリを作るなら、QtのPythonバインディングであるPyQtとPySideが最有力です。

本記事では、初心者が最短で実用的なアプリを作って配布できることを目標に、選び方から開発環境構築、基本GUI、実用機能、Qt Designerの活用、PyInstallerによる配布までを丁寧に解説します。

PyQtとPySideの基礎と選び方
開発環境の準備とインストール
GUIの基本の作り方
実用機能と配布
まとめ

PyQtとPySideの基礎と選び方

PyQt/PySideとは

PyQtとPySideは、クロスプラットフォームのGUIフレームワークQtをPythonから利用するためのバインディングです。

Windows、macOS、Linuxで同じコードが動きます。

現在はQt6系が主流で、PyQt6とPySide6が広く使われています。

APIは非常に似ており、どちらを選んでも高機能なアプリを構築できます。

重要

ライセンス形態に違いがあるため、商用配布やソースコード公開方針に応じて選択を検討します。

以下に主要な違いをまとめます。

観点	PyQt6	PySide6
提供元	Riverbank Computing	The Qt Company
ライセンス	GPLまたは商用ライセンス	LGPLまたは商用ライセンス
商用配布	ソース非公開の場合は商用ライセンスが必要	LGPL準拠で配布可能な場合が多い
パッケージ名	PyQt6	PySide6
UI変換ツール	pyuic6、pyrcc6	pyside6-uic、pyside6-rcc
Designer	別途pyqt6-toolsなどで導入	pyside6-designerを同梱
API傾向	若干早く新機能が入ることも	公式実装でC++ Qtに忠実
ドキュメント	PyQt6固有ドキュメント＋Qt公式	Qt公式ドキュメントをそのまま参照

どちらを選んでも、通常のデスクトップアプリ開発では機能差はほぼ問題になりません。

初心者の選び方(迷ったらどっち)

迷ったらPySide6をおすすめします。

理由は以下の通りです。

インストールがシンプルで、pyside6-designerでQt Designerがすぐ使えること、ライセンスがLGPLで扱いやすいことが挙げられます。

一方、既存教材がPyQt主体の場合や、会社の方針でPyQtが推奨される場合はPyQt6でも問題ありません。

APIの書き方はほぼ同じで、サンプルコードの読み替えも容易です。

商用配布や社外提供を予定する場合は、必ずライセンス条件を確認してください。

よく使う用語(Qt/Widget/Qt Designer)

QtはGUIだけでなくネットワーク、マルチスレッド、マルチメディアなど幅広い機能を提供するフレームワークです。

本記事では主にWidgets系のGUIを扱います。

用語の要点を押さえましょう。

用語	説明
Qt	クロスプラットフォームのC++フレームワーク。Pythonからは PyQt や PySide で利用可能。
Widget	ボタンやラベルなどの GUI部品。
QMainWindow	メインウィンドウの土台。メニュー・ツールバー・ステータスバーを持てる。
Layout	ウィジェットを整列させる仕組み。例: QVBoxLayout, QGridLayout。
Signal / Slot	イベント(クリックなど)と処理を結びつける仕組み。
Qt Designer	ドラッグ&ドロップでGUIを設計するツール。保存形式は .uiファイル。
uic	.uiファイル → Pythonコードに変換するツール。例: `pyuic6`, `pyside6-uic`。
qrc / rcc	画像などのリソース定義(.qrc)をバイナリに変換するツール。例: `pyrcc6`, `pyside6-rcc`。

開発環境の準備とインストール

必要なもの(Python/pip/VS Code)

Python 3.9以上を推奨します。

pipはPythonに同梱されていることが多いですが、最新化しておくと安心です。

エディタとしてVS Codeが扱いやすく、拡張機能(Python)を入れると補完やデバッグが快適になります。

Pythonの入手: https://www.python.org/
VS Codeの入手: https://code.visualstudio.com/

仮想環境の作成(venv)

プロジェクトごとに依存関係を分離するため、venvを使います。

Windows PowerShellの例:

PowerShell

# プロジェクト用フォルダを作成して移動
mkdir MyQtApp
cd MyQtApp

# 仮想環境の作成
python -m venv .venv

# 有効化
. .\.venv\Scripts\Activate.ps1

# pipの更新
python -m pip install --upgrade pip

macOS/Linuxの例:

Shell

# プロジェクト用フォルダを作成して移動
mkdir MyQtApp
cd MyQtApp

# 仮想環境の作成
python3 -m venv .venv

# 有効化
source .venv/bin/activate

# pipの更新
python -m pip install --upgrade pip

PyQtのインストール(pip)

PyQt6をインストールします。

Shell

python -m pip install PyQt6

動作確認:

Shell

python -c "import PyQt6, PyQt6.QtWidgets as W; print('PyQt6 OK, QWidget=', hasattr(W,'QWidget'))"

実行結果

PyQt6 OK, QWidget= True

PySideのインストール(pip)

PySide6のインストールは以下です。

Shell

python -m pip install PySide6

動作確認:

Shell

python -c "import PySide6, PySide6.QtWidgets as W; print('PySide6 OK, QPushButton=', hasattr(W,'QPushButton'))"

実行結果

PySide6 OK, QPushButton= True

最小アプリ(Hello Window)

はじめてのウィンドウを表示してみます。

PyQt6版とPySide6版を用意します。

PyQt6版 Hello Window

Python

# hello_pyqt6.py
# 最小のウィンドウを開くPyQt6サンプル
from PyQt6.QtWidgets import QApplication, QLabel
from PyQt6.QtGui import QFont
import sys

def main():
    app = QApplication(sys.argv)
    # ラベル1つのシンプルなウィンドウ
    label = QLabel("Hello, PyQt6!")
    label.setFont(QFont("Meiryo", 16))  # 日本語フォント例
    label.resize(300, 80)
    label.show()
    print("PyQt6 app started")  # コンソール出力がおこなわれます
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

Shell

python hello_pyqt6.py

実行結果

PyQt6 app started

PySide6版 Hello Window

Python

# hello_pyside6.py
# 最小のウィンドウを開くPySide6サンプル
from PySide6.QtWidgets import QApplication, QLabel
from PySide6.QtGui import QFont
import sys

def main():
    app = QApplication(sys.argv)
    label = QLabel("Hello, PySide6!")
    label.setFont(QFont("Meiryo", 16))
    label.resize(300, 80)
    label.show()
    print("PySide6 app started")
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

GUIの基本の作り方

メインウィンドウ(QMainWindow)

Qtのアプリケーションは、大枠としてQMainWindowを基盤にすると便利です。

QMainWindowは、メニューやツールバー、ステータスバーといった「アプリっぽい」要素を簡単に追加できる仕組みを備えています。

一方、単純なウィジェットだけを置くならQWidgetベースでも作れますが、本格的なアプリを作るならQMainWindowを使うのが標準的です。

Python

# basic_mainwindow.py
# QMainWindowを使った基礎構造
import sys
from PySide6.QtWidgets import QApplication, QMainWindow, QWidget, QLabel, QVBoxLayout
from PySide6.QtGui import QIcon

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("基本のメインウィンドウ")
        # アイコンがあれば設定できます
        # self.setWindowIcon(QIcon("app_icon.png"))

        # 中央ウィジェットとレイアウトを用意
        central = QWidget(self)
        layout = QVBoxLayout(central)
        layout.addWidget(QLabel("ようこそ! ここにウィジェットを追加していきます。"))
        self.setCentralWidget(central)

        # ステータスバーの表示
        self.statusBar().showMessage("準備完了")

def main():
    app = QApplication(sys.argv)
    w = MainWindow()
    w.resize(480, 320)
    w.show()
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

PyQt6で動かす場合は、先頭のインポートをPySide6の部分をPyQt6に読み替えます。

中央ウィジェット (setCentralWidget)：アプリのメイン部分を担当。
メニューやツールバー：後から簡単に追加可能。
ステータスバー：進行状況やヒントを表示できる。

コード例では「ラベルを置いただけの最小構成」になっていますが、ここにレイアウトを組んだウィジェットを自由に追加していけます。

サイズやウィンドウタイトルの設定、アイコンの設定もQMainWindowが面倒を見てくれます。

ボタンとテキスト(QPushButton/QLabel/QLineEdit)

GUIアプリの基本は「入力 → 処理 → 出力」です。Qtでは以下の3要素でこれを実現できます:

QLineEdit: ユーザーからテキストを入力してもらう部品
QPushButton: 処理のトリガーになるボタン
QLabel: 結果を表示する出力部品

そして重要なのがシグナルとスロットの仕組みです。

Qtでは「イベントが起きたら（シグナル）、この関数を実行する（スロット）」という接続ができます。

これにより、ボタンが押されたときに入力テキストを取得し、ラベルに反映する処理を直感的に書けます。

ボタンを押してテキストを更新する基本的な例です。

Python

# widgets_basic.py
# ボタン、ラベル、テキスト入力の基本
import sys
from PySide6.QtWidgets import (
    QApplication, QMainWindow, QWidget,
    QVBoxLayout, QHBoxLayout, QLabel, QLineEdit, QPushButton
)

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("ウィジェットの基本")

        # 中央領域のセットアップ
        central = QWidget(self)
        main_layout = QVBoxLayout(central)

        # 入力行とボタンを横並びに
        row = QHBoxLayout()
        self.edit = QLineEdit()
        self.edit.setPlaceholderText("名前を入力してください")
        self.button = QPushButton("あいさつ")
        row.addWidget(self.edit)
        row.addWidget(self.button)

        self.label = QLabel("こんにちは、Qt!")
        main_layout.addLayout(row)
        main_layout.addWidget(self.label)

        self.setCentralWidget(central)

        # シグナルとスロットの接続
        self.button.clicked.connect(self.say_hello)

    def say_hello(self):
        name = self.edit.text().strip() or "名無し"
        self.label.setText(f"こんにちは、{name}さん!")
        print("Button clicked, label updated.")  # コンソール確認用

def main():
    app = QApplication(sys.argv)
    w = MainWindow()
    w.show()
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

この例では、

Python

self.button.clicked.connect(self.say_hello)

で「クリックされたらsay_hello()を呼び出す」ようにしています。

初心者がつまづきやすいのは「関数呼び出し」ではなく「関数参照」を渡す点です。

self.say_helloと書き、括弧は付けません（括弧をつけるとその場で実行されてしまう）。

レイアウトの基本(QVBoxLayout/QGridLayout)

縦積みのQVBoxLayout、表形式のQGridLayoutを使うと、リサイズに強いUIになります。

Python

# layouts_basic.py
# GridLayoutでラベルと入力を整列
import sys
from PySide6.QtWidgets import (
    QApplication, QMainWindow, QWidget,
    QGridLayout, QLabel, QLineEdit, QPushButton
)

class GridForm(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("レイアウトの基本")
        central = QWidget(self)
        grid = QGridLayout(central)

        grid.addWidget(QLabel("姓"), 0, 0)
        self.last_name = QLineEdit()
        grid.addWidget(self.last_name, 0, 1)

        grid.addWidget(QLabel("名"), 1, 0)
        self.first_name = QLineEdit()
        grid.addWidget(self.first_name, 1, 1)

        self.submit = QPushButton("登録")
        grid.addWidget(self.submit, 2, 0, 1, 2)  # 2列にまたがる

        self.setCentralWidget(central)
        self.submit.clicked.connect(self.on_submit)

    def on_submit(self):
        print("登録:", self.last_name.text(), self.first_name.text())

def main():
    app = QApplication(sys.argv)
    w = GridForm()
    w.show()
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

シグナルとスロット(クリック処理)

Qtの核となる仕組みです。

シグナル(イベント通知)をスロット(関数)に接続します。

直接メソッドを接続: button.clicked.connect(self.on_click)
値を渡したいときはlambda: button.clicked.connect(lambda: self.process(value))

Python

# signals_slots.py
# シグナルとスロットの例
from PySide6.QtWidgets import QApplication, QPushButton
import sys

def on_click():
    print("clicked!")

app = QApplication(sys.argv)
btn = QPushButton("Click me")
btn.clicked.connect(on_click)  # シグナル→スロット
btn.show()
app.exec()

実行結果

clicked!

画面設計ツールの使い方(Qt Designer)

GUIをドラッグ&ドロップで設計できるのがQt Designerです。

PySide6の場合: pyside6-designerコマンドで起動できます。
PyQt6の場合: pyqt6-toolsを導入しpyqt6-tools designerで起動します(サードパーティ)。

作った.uiは2通りで使えます。

1つ目はPythonに変換する方法です。

Shell

# PySide6
pyside6-uic mainwindow.ui -o ui_mainwindow.py

# PyQt6
pyuic6 mainwindow.ui -o ui_mainwindow.py

変換後の使い方:

Python

# use_ui_compiled.py
# uicで生成したui_mainwindow.pyを利用
import sys
from PySide6.QtWidgets import QApplication, QMainWindow
from ui_mainwindow import Ui_MainWindow  # uic生成物

class MainWindow(QMainWindow, Ui_MainWindow):
    def __init__(self):
        super().__init__()
        self.setupUi(self)  # Designerで配置したUIを初期化
        # ここでシグナル接続などを追記
        # 例: self.pushButton.clicked.connect(self.handle_click)

def main():
    app = QApplication(sys.argv)
    w = MainWindow()
    w.show()
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

2つ目は動的ロード(QUiLoader)ですが、初心者にはuic変換が分かりやすいです。

ウィンドウタイトルとアイコン設定

タイトルはsetWindowTitle、アイコンはsetWindowIconで設定します。

Python

# window_title_icon.py
from PySide6.QtWidgets import QApplication, QMainWindow
from PySide6.QtGui import QIcon
import sys

app = QApplication(sys.argv)
w = QMainWindow()
w.setWindowTitle("アプリ名 - サンプル")
w.setWindowIcon(QIcon("app_icon.png"))  # ファイルパスまたはリソース
w.resize(400, 200)
w.show()
sys.exit(app.exec())

画像をPythonに埋め込む場合はリソース(.qrc)を使います。

XML

<!-- resources.qrc -->
<RCC>
  <qresource prefix="/">
    <file>app_icon.png</file>
  </qresource>
</RCC>

Shell

# PySide6
pyside6-rcc resources.qrc -o resources_rc.py

# PyQt6
pyrcc6 resources.qrc -o resources_rc.py

Python側ではfrom resources_rc import *とすれば:/app_icon.pngで参照できます。

実用機能と配布

ここからは、実用的なアプリに欠かせない構成要素を加えていきます。

以下の例は一つのアプリにまとめて示します。

Python

# practical_app.py
# メニュー、ツールバー、ダイアログ、ステータスバー、設定、タイマー、CSV/画像の読み書き
import sys
import csv
from datetime import datetime
from PySide6.QtCore import QSettings, QTimer, Qt
from PySide6.QtGui import QAction, QIcon, QKeySequence
from PySide6.QtWidgets import (
    QApplication, QMainWindow, QFileDialog, QMessageBox, QLabel,
    QTableWidget, QTableWidgetItem, QToolBar, QWidget, QVBoxLayout, QPushButton
)

class PracticalMainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("実用アプリの土台")
        # アイコンがあれば設定
        # self.setWindowIcon(QIcon("app_icon.png"))

        # 設定オブジェクトを用意
        self.settings = QSettings("ExampleCompany", "PracticalApp")

        # 中央ウィジェット: 画像プレビューとテーブル
        central = QWidget(self)
        layout = QVBoxLayout(central)
        self.info_label = QLabel("ファイルを開くと内容がここに表示されます")
        self.table = QTableWidget(0, 3)
        self.table.setHorizontalHeaderLabels(["列1", "列2", "列3"])
        self.preview_button = QPushButton("CSVサンプルを読み込む")
        layout.addWidget(self.info_label)
        layout.addWidget(self.table)
        layout.addWidget(self.preview_button)
        self.setCentralWidget(central)

        # メニュー/ツールバー/ステータスバーのセットアップ
        self._create_actions()
        self._create_menus()
        self._create_toolbar()
        self.statusBar().showMessage("準備完了")

        # シグナル接続
        self.preview_button.clicked.connect(self.load_sample_csv)

        # タイマーで時計表示を更新
        self.clock_timer = QTimer(self)
        self.clock_timer.timeout.connect(self._tick_clock)
        self.clock_timer.start(1000)  # 1秒ごと

        # ウィンドウ状態の復元
        self._restore_settings()

    def _create_actions(self):
        self.act_open = QAction(QIcon(), "開く...", self)
        self.act_open.setShortcut(QKeySequence.StandardKey.Open)
        self.act_open.triggered.connect(self.open_file)

        self.act_save = QAction(QIcon(), "保存...", self)
        self.act_save.setShortcut(QKeySequence.StandardKey.Save)
        self.act_save.triggered.connect(self.save_file)

        self.act_quit = QAction("終了", self)
        self.act_quit.setShortcut(QKeySequence.StandardKey.Quit)
        self.act_quit.triggered.connect(self.close)

        self.act_about = QAction("このアプリについて", self)
        self.act_about.triggered.connect(self.show_about)

    def _create_menus(self):
        m_file = self.menuBar().addMenu("ファイル")
        m_file.addAction(self.act_open)
        m_file.addAction(self.act_save)
        m_file.addSeparator()
        m_file.addAction(self.act_quit)

        m_help = self.menuBar().addMenu("ヘルプ")
        m_help.addAction(self.act_about)

    def _create_toolbar(self):
        tb = QToolBar("メインツールバー", self)
        tb.setIconSize(tb.iconSize())  # 必要ならサイズ調整
        tb.addAction(self.act_open)
        tb.addAction(self.act_save)
        self.addToolBar(tb)

    def _tick_clock(self):
        now = datetime.now().strftime("%H:%M:%S")
        self.statusBar().showMessage(f"準備完了 | {now}")

    def open_file(self):
        # 最後に開いたディレクトリを既定に
        last_dir = self.settings.value("last_dir", "")
        path, _ = QFileDialog.getOpenFileName(
            self, "ファイルを開く", last_dir,
            "CSVファイル (*.csv);;すべてのファイル (*.*)"
        )
        if not path:
            return
        self.settings.setValue("last_dir", QFileDialog.directory().path() if hasattr(QFileDialog, "directory") else "")  # 互換のための保険
        self.load_csv(path)

    def save_file(self):
        last_dir = self.settings.value("last_dir", "")
        path, _ = QFileDialog.getSaveFileName(
            self, "ファイルを保存", last_dir,
            "CSVファイル (*.csv)"
        )
        if not path:
            return
        self.save_csv(path)

    def show_about(self):
        QMessageBox.information(
            self,
            "このアプリについて",
            "PySide6で構築した実用アプリのひな型です。\nメニュー、ツールバー、ダイアログ、設定、タイマー、CSVの読み書きを備えます。"
        )

    def load_sample_csv(self):
        # メモリ上のサンプルを読み込む例
        rows = [
            ["りんご", "100", "赤"],
            ["バナナ", "80", "黄"],
            ["ぶどう", "120", "紫"]
        ]
        self._set_table(rows)
        self.info_label.setText("サンプルCSVを読み込みました")
        print("Sample CSV loaded")

    def load_csv(self, path: str):
        rows = []
        try:
            with open(path, newline="", encoding="utf-8") as f:
                reader = csv.reader(f)
                rows = [row for row in reader]
            self._set_table(rows)
            self.info_label.setText(f"読み込み完了: {path}")
            print(f"Loaded CSV: {path}")
        except Exception as e:
            QMessageBox.critical(self, "読み込みエラー", str(e))

    def save_csv(self, path: str):
        try:
            with open(path, "w", newline="", encoding="utf-8") as f:
                writer = csv.writer(f)
                for r in range(self.table.rowCount()):
                    row = []
                    for c in range(self.table.columnCount()):
                        item = self.table.item(r, c)
                        row.append(item.text() if item else "")
                    writer.writerow(row)
            self.info_label.setText(f"保存完了: {path}")
            print(f"Saved CSV: {path}")
            self.settings.setValue("last_dir", path)
        except Exception as e:
            QMessageBox.critical(self, "保存エラー", str(e))

    def _set_table(self, rows):
        # rowsの列数に合わせてテーブル列数を調整
        max_cols = max((len(r) for r in rows), default=0)
        self.table.setColumnCount(max_cols if max_cols > 0 else self.table.columnCount())
        self.table.setRowCount(len(rows))
        for r, row in enumerate(rows):
            for c, value in enumerate(row):
                self.table.setItem(r, c, QTableWidgetItem(value))

    def _restore_settings(self):
        # ウィンドウサイズや位置を復元
        geom = self.settings.value("geometry")
        if geom is not None:
            self.restoreGeometry(geom)
        else:
            self.resize(800, 500)

    def closeEvent(self, event):
        # 終了時にウィンドウ状態を保存
        self.settings.setValue("geometry", self.saveGeometry())
        super().closeEvent(event)

def main():
    app = QApplication(sys.argv)
    w = PracticalMainWindow()
    w.show()
    sys.exit(app.exec())

if __name__ == "__main__":
    main()

このアプリは、メニューとツールバーからファイルを開く・保存でき、ステータスバーに時計を表示します。

QSettingsでウィンドウ状態と直近のパスを保持するため、次回起動時に状態が復元されます。

メニューとツールバーの追加

上記サンプルの_create_menusと_create_toolbarのように、QActionを作ってメニューに追加し、同じアクションをツールバーにも入れると、ショートカット、メニュー、ボタンが一貫して動作します。

ダイアログ(ファイルを開く/保存)

QFileDialog.getOpenFileNameやgetSaveFileNameを使います。

フィルタ文字列("CSVファイル (.csv);;すべてのファイル (.*)")はOS標準ダイアログに準拠します。

ステータスバーと通知メッセージ

statusBar().showMessage("メッセージ")で一時表示、QMessageBoxで情報・警告・エラーを表示します。

ユーザーへのフィードバックは丁寧に出すと使いやすいアプリになります。

設定の保存(QSettings)

QSettingsはOSごとに適切な場所に保存します。

OS	保存先の例
Windows	レジストリ`(HKEY_CURRENT_USER\Software\Company\App)`
macOS	`~/Library/Preferences`
Linux	`~/.config`

キー名は自分で決められるため、geometryやlast_dirなど分かりやすく命名しましょう。

タイマーで処理を定期実行(QTimer)

QTimerで一定間隔の処理を実行できます。

時計表示、定期的な自動保存、バックグラウンドの進捗監視などに使えます。

上のサンプルでは1秒ごとにステータスバーの時計を更新しています。

画像やCSVの読み書き

画像はQPixmapやQImageで読み込み、QLabelなどに表示できます。
CSVは標準のcsvモジュールで読み書きし、QTableWidgetに配置すると見やすくなります。

画像表示の最小例:

Python

# image_preview.py
from PySide6.QtWidgets import QApplication, QLabel
from PySide6.QtGui import QPixmap
import sys

app = QApplication(sys.argv)
label = QLabel()
pix = QPixmap("sample.png")
label.setPixmap(pix)
label.resize(pix.size())
label.show()
print("Image loaded:", not pix.isNull())
sys.exit(app.exec())

実行結果

Image loaded: True

アプリの配布(PyInstaller)

完成したアプリはPyInstallerで実行ファイル化できます。

基本的な手順:

Shell

python -m pip install pyinstaller

# GUIアプリとしてコンソールを出さない場合
pyinstaller --name PracticalApp --windowed --onefile practical_app.py

# アイコンを付ける場合
# Windows: .ico, macOS: .icns
pyinstaller --name PracticalApp --windowed --onefile --icon app_icon.ico practical_app.py

生成物はdistフォルダに作られます。

一部のQtモジュールはプラグインが必要な場合があります。

その際は--hidden-importで追加入力します。

Shell

# SVGや印刷サポートを使う場合の例
pyinstaller --windowed --onefile \
  --hidden-import PySide6.QtSvg \
  --hidden-import PySide6.QtPrintSupport \
  practical_app.py

実機検証はターゲットOSごとに行うのが確実です。

Windowsで配布するならWindows上でビルド・検証することをおすすめします。