Claude Code を WSL で使って QGIS GUI プラグインを開発する環境を作る
1. はじめに
Windows 11 Pro 環境で、Claude Code を WSL 上で実行しながら、QGIS の GUI プラグインを開発するための環境構築メモです。
今回は、以下の環境を前提にします。
* Windows 11 Pro
* WSL 2
* Ubuntu on WSL
* OSGeo4W 環境構築済み
* QGIS インストール済み
* Plugin Builder インストール済み
* git環境構築済み
* 外部 Python ライブラリは使わない
* UI は PyQt5 系、つまり `qgis.PyQt` を使う
* Claude Code は WSL 上で実行する
* QGIS 本体は Windows 側で実行する
ポイントは、Claude Code は WSL 側で動かし、QGIS/OSGeo4W は Windows 側で動かすことです。
2. 全体構成
開発の流れは次のようにします。
Windows 11 Pro
├─ OSGeo4W
│ └─ QGIS
│ └─ Plugin Builder
│
└─ WSL 2 / Ubuntu
└─ Claude Code
└─ Windows 側のプラグインフォルダーを編集
開発の流れです。
Plugin Builder で雛形作成
↓
Windows 側の C:\qgis_plugin_dev に配置
↓
WSL から /mnt/c/qgis_plugin_dev を開く
↓
Claude Code で修正
↓
Windows 側の QGIS で動作確認
↓
問題なければ Git commit
3. WSL の準備
Windows PowerShell を管理者として起動し、WSL をインストールします。
wsl --install
インストール後、PC を再起動します。
Ubuntu が起動したら、ユーザー名とパスワードを設定します。
WSL の状態を確認します。
wsl -l -v
Ubuntu が WSL 2 になっていれば OK です。
NAME STATE VERSION
* Ubuntu Running 2
4. WSL 側の基本パッケージ更新
Ubuntu 側で実行します。
sudo apt update
sudo apt upgrade -y
Git も入れておきます。
sudo apt install -y git curl ca-certificates
5. Claude Code のインストール
Claude Code は WSL 側にインストールします。
Ubuntu のターミナルで実行します。
curl -fsSL https://claude.ai/install.sh | bash
インストール後、シェルを再読み込みします。
source ~/.bashrc
確認します。
claude --version
詳細確認も行います。
claude doctor
Claude Code を初回起動します。
claude
ブラウザ認証が求められるので、案内に従ってログインします。
6. 開発フォルダー構成
QGIS は Windows 側で動くため、プラグイン本体は Windows 側に置きます。
C:\qgis_plugin_dev
├─ plugins
│ └─ MyQgisPlugin
│ ├─ __init__.py
│ ├─ metadata.txt
│ ├─ my_qgis_plugin.py
│ ├─ my_qgis_plugin_dialog.py
│ ├─ my_qgis_plugin_dialog_base.ui
│ ├─ resources.qrc
│ ├─ resources.py
│ ├─ icon.png
│ └─ CLAUDE.md
├─ docs
├─ sample_data
├─ run_qgis_dev.bat
└─ README.md
WSL から見ると、同じフォルダーは次のパスになります。
/mnt/c/qgis_plugin_dev
プラグインフォルダーは次です。
/mnt/c/qgis_plugin_dev/plugins/MyQgisPlugin
7. Plugin Builder で雛形を作成する
Windows 側で QGIS を起動し、Plugin Builder で GUI 付きプラグインを作成します。
設定例です。
Plugin name : MyQgisPlugin
Class name : MyQgisPlugin
Module name : my_qgis_plugin
Template : Tool button with dialog
Output folder : C:\qgis_plugin_dev\plugins
GUI を使うため、ダイアログ付きテンプレートを選択します。
8. QGIS 開発用起動バッチ
Windows 側に C:\qgis_plugin_dev\run_qgis_dev.bat を作成します。
.bat は Windows 用に Shift_JIS / cp932 + CRLF で保存します。
@echo off
rem ============================================================
rem QGIS Plugin Development Launcher
rem Windows 11 Pro + OSGeo4W + QGIS 3.x 用
rem
rem 開発中のプラグインフォルダーを QGIS_PLUGINPATH に追加して、
rem QGIS を開発用プロファイルで起動します。
rem ============================================================
set OSGEO4W_ROOT=C:\OSGeo4W
set DEV_PLUGIN_DIR=C:\qgis_plugin_dev\plugins
rem OSGeo4W の基本環境を読み込みます。
call "%OSGEO4W_ROOT%\bin\o4w_env.bat"
rem QGIS 3.x / Qt5 / Python3 環境を読み込みます。
call "%OSGEO4W_ROOT%\bin\qt5_env.bat"
call "%OSGEO4W_ROOT%\bin\py3_env.bat"
rem 開発中プラグインの検索パスを追加します。
set QGIS_PLUGINPATH=%DEV_PLUGIN_DIR%
rem QGIS LTR を起動します。
rem qgis-ltr.bat が無い場合は qgis.bat に変更してください。
start "" cmd /c ""%OSGEO4W_ROOT%\bin\qgis-ltr.bat" --profile qgis_plugin_dev"
通常版 QGIS の場合は、以下の部分を変更します。
qgis-ltr.bat
を、
qgis.bat
にします。
9. WSL からプラグインフォルダーへ移動する
Ubuntu 側で、Windows 側のプラグインフォルダーに移動します。
cd /mnt/c/qgis_plugin_dev/plugins/MyQgisPlugin
ファイルを確認します。
ls -la
10. Git で管理する
Claude Code を使う前に、必ず Git 管理します。
WSL 側で実行します。
cd /mnt/c/qgis_plugin_dev/plugins/MyQgisPlugin
git init
git add .
git commit -m "Initial Plugin Builder template"
Claude Code で修正した後は、必ず差分を確認します。
git status
git diff
11. 改行コードに注意する
QGIS プラグインの Python ファイルは UTF-8 で問題ありません。
ただし、Windows 側で実行する .bat は次の形式にします。
文字コード: Shift_JIS / cp932
改行コード: CRLF
WSL 側で .bat を編集すると、LF 改行になりやすいため注意します。
.gitattributes を作成しておくと安全です。
*.py text eol=lf
*.ui text eol=lf
*.qrc text eol=lf
*.txt text eol=crlf
*.bat text eol=crlf
*.md text eol=lf
12. CLAUDE.md を作成する
Claude Code では、プロジェクトルートに CLAUDE.md を置いておくと、開発ルールを共有しやすくなります。
/mnt/c/qgis_plugin_dev/plugins/MyQgisPlugin/CLAUDE.md を作成します。
# QGIS Plugin Development Rules
このプロジェクトは Windows 11 Pro + OSGeo4W + QGIS 3.x 用の QGIS GUI プラグインです。
Claude Code は WSL 上で実行しますが、QGIS 本体と OSGeo4W は Windows 側で実行します。
## 基本条件
- Plugin Builder で生成された構成を壊さない
- UI は QGIS 付属の PyQt5 環境を使う
- import は `PyQt5` 直指定ではなく `qgis.PyQt` を使う
- PySide6 は使わない
- 外部ライブラリは使わない
- QGIS 標準 API と Python 標準ライブラリだけで実装する
- 日本語コメントと docstring を追加する
- 大規模変更を行う前に、必ず変更方針を示す
## 実行環境の注意
- Claude Code は WSL 側で実行する
- QGIS は Windows 側で実行する
- プラグイン本体は `C:\qgis_plugin_dev\plugins` に置く
- WSL からは `/mnt/c/qgis_plugin_dev/plugins` として参照する
- Windows 用 `.bat` は cp932 + CRLF で保存する
## import ルール
OK:
from qgis.PyQt.QtWidgets import QAction, QDialog, QMessageBox
from qgis.PyQt.QtGui import QIcon
from qgis.PyQt.QtCore import Qt
from qgis.core import QgsProject, QgsMessageLog, Qgis
NG:
from PyQt5.QtWidgets import QDialog
from PySide6.QtWidgets import QDialog
## 修正ルール
* `metadata.txt` を不用意に変更しない
* `__init__.py` を不用意に変更しない
* `resources.qrc` を変更した場合は `resources.py` の再生成を確認する
* 1回の修正は小さくする
* 修正後は `git diff` で確認する
* 実行確認は Windows 側の QGIS 本体で行う
13. Claude Code の起動
WSL 側でプラグインフォルダーに移動します。
cd /mnt/c/qgis_plugin_dev/plugins/MyQgisPlugin
claude
最初に次のように依頼します。
このリポジトリは QGIS 3.x 用の GUI プラグインです。
Claude Code は WSL 上で実行していますが、QGIS 本体は Windows 側で実行します。
まず CLAUDE.md とファイル構成を確認してください。
その後、Plugin Builder の構成を壊さない前提で、開発方針を簡潔に説明してください。
14. Claude Code への依頼例
最初は小さな機能から依頼します。
現在の Plugin Builder 生成コードを確認してください。
次の機能を追加してください。
機能:
- ダイアログに「選択レイヤを取得」ボタンを追加
- 現在選択されているレイヤ名を QLabel に表示
- レイヤが未選択の場合は QMessageBox で警告表示
- QGIS のログパネルにも処理結果を出力
条件:
- qgis.PyQt を使う
- 外部ライブラリは使わない
- QGIS 標準 API と Python 標準ライブラリだけで実装
- Plugin Builder の構成を壊さない
- 日本語コメントと docstring を追加
- Windows 側 QGIS で動くコードにする
- WSL 側だけで完結するコードにしない
- 変更前に実装方針を示す
15. QGIS プラグインでの import ルール
QGIS プラグインでは、次のように qgis.PyQt を使います。
from qgis.PyQt.QtWidgets import QAction, QDialog, QMessageBox
from qgis.PyQt.QtGui import QIcon
from qgis.PyQt.QtCore import Qt
from qgis.core import QgsProject, QgsMessageLog, Qgis
避けたい書き方です。
from PyQt5.QtWidgets import QDialog
from PySide6.QtWidgets import QDialog
QGIS の Python 環境に合わせるため、基本は qgis.PyQt 経由にします。
16. レイヤ取得のサンプルコード
QGIS で現在選択されているアクティブレイヤを取得する例です。
from qgis.PyQt.QtWidgets import QMessageBox
from qgis.core import QgsMessageLog, Qgis
def get_current_layer_name(self):
"""
QGIS で現在選択されているアクティブレイヤ名を取得します。
Returns
-------
str | None
アクティブレイヤ名。
レイヤが選択されていない場合は None を返します。
"""
layer = self.iface.activeLayer()
if layer is None:
QMessageBox.warning(
self.dlg,
"レイヤ未選択",
"現在選択されているレイヤがありません。"
)
QgsMessageLog.logMessage(
"アクティブレイヤが選択されていません。",
"MyQgisPlugin",
Qgis.Warning
)
return None
layer_name = layer.name()
QgsMessageLog.logMessage(
f"選択レイヤ: {layer_name}",
"MyQgisPlugin",
Qgis.Info
)
return layer_name
17. GUI 修正の流れ
GUI を変更する場合は、次の流れにします。
1. Windows 側の Qt Designer で .ui ファイルを編集
2. ボタンやラベルに objectName を設定
3. WSL 側の Claude Code で Python 側の signal/slot を接続
4. Windows 側の QGIS でプラグインを再読み込み
5. QGIS のログメッセージを確認
例です。
self.dlg.pushButtonGetLayer.clicked.connect(self.on_get_layer_clicked)
def on_get_layer_clicked(self):
"""
「選択レイヤを取得」ボタンが押されたときの処理です。
"""
layer = self.iface.activeLayer()
if layer is None:
QMessageBox.warning(
self.dlg,
"確認",
"レイヤが選択されていません。"
)
return
self.dlg.labelLayerName.setText(layer.name())
18. QGIS で動作確認する
Windows 側で以下を実行します。
C:\qgis_plugin_dev\run_qgis_dev.bat
QGIS が起動したら、プラグインを有効化します。
プラグイン
└─ プラグインの管理とインストール
エラー確認は次で行います。
表示
└─ パネル
└─ ログメッセージ
19. 開発時の確認手順
毎回、次の流れで確認します。
1. WSL 側で git status を確認
2. Claude Code に小さな修正を依頼
3. WSL 側で git diff を確認
4. Windows 側で QGIS を起動
5. プラグインを有効化
6. QGIS 上で動作確認
7. ログメッセージパネルを確認
8. 問題なければ WSL 側で git commit
コミット例です。
git add .
git commit -m "Add active layer display button"
20. WSL 実行時の注意点
20.1. QGIS は WSL ではなく Windows 側で動かす
Claude Code は WSL 側で動かしますが、QGIS プラグインの実行確認は Windows 側の QGIS で行います。
Claude Code: WSL
QGIS : Windows
OSGeo4W : Windows
20.2. Windows 側のファイルを WSL から編集する
プラグインは Windows 側の次に置きます。
C:\qgis_plugin_dev\plugins
WSL 側では次として参照します。
/mnt/c/qgis_plugin_dev/plugins
20.3. .bat の文字コードに注意する
Windows 側で実行する .bat は、次で保存します。
Shift_JIS / cp932 + CRLF
WSL 側で .bat を大きく編集する場合は、改行コードが LF にならないように注意します。
20.4. PyQt5 を WSL 側に入れない
今回のプラグインは、Windows 側 QGIS に同梱された PyQt5 を使います。
そのため、WSL 側に PyQt5 を入れる必要はありません。
pip install PyQt5
のような作業は不要です。
20.5. 外部ライブラリを追加しない
今回の方針では、外部ライブラリは使いません。
使うのは次だけです。
- QGIS 標準 API
- qgis.PyQt
- Python 標準ライブラリ
21. 外部ライブラリなしでできること
外部ライブラリを使わなくても、QGIS 標準 API だけで多くの処理ができます。
- アクティブレイヤの取得
- ベクタレイヤの属性取得
- フィーチャのループ処理
- ジオメトリ取得
- 面積・長さ計算
- 属性テーブルの表示
- 新規メモリレイヤ作成
- GeoPackage / Shapefile 出力
- CRS 取得
- 地図キャンバス操作
- 選択フィーチャ取得
- QGIS ログへの出力
最初は、次のようなプラグインを作ると練習しやすいです。
レイヤ情報確認プラグイン
機能:
- アクティブレイヤ名を表示
- CRS を表示
- フィーチャ数を表示
- 属性フィールド一覧を表示
- 選択フィーチャ数を表示
- ログパネルに処理結果を出力
22. まとめ
Claude Code を WSL 上で使って QGIS プラグインを作る場合、重要なのは次の点です。
- Claude Code は WSL 側で実行する
- QGIS と OSGeo4W は Windows 側で実行する
- プラグイン本体は C:\qgis_plugin_dev\plugins に置く
- WSL からは /mnt/c/qgis_plugin_dev/plugins として編集する
- Plugin Builder の構成を壊さない
- PyQt5 は qgis.PyQt 経由で使う
- PySide6 は使わない
- 外部ライブラリは使わない
- CLAUDE.md に開発ルールを書く
- 修正後は必ず Windows 側 QGIS で動作確認する
- Git で差分確認してから commit する
この構成にしておくと、Claude Code を WSL 上で使いながら、Windows 側の QGIS プラグインを安全に開発できます。