久しぶりに自作キーボードを触るかとなって最新の環境で色々と作業しようかと思っていたのですが、色々と変わっていたのと今回はWLS2を使ってビルドしてみようと思ったので備忘録の紹介です。ちなみに私は今までDebianやUbuntuなど適当に家に転がっているLinuxマシンでビルドしていました。
まず、QMK公式に行くとここにインストールの方法が書いてあるのですが、WSL2はあくまでWidows Subsystem Linuxの名前の通りWindowsではなくLinuxのインストール方法を見る必要があります。以前まではそれなりに楽にできたイメージがあったのですんなりいくだろうと思いきや結構最初の方でエラーが出ました。それでもすんなり解決できるのですが、困っている人やこの辺りに疎い人のために備忘録として残しておこうかと思います。
WSL2のインストール方法については割愛します。というかそこまで難しくないのと情報がネットの海にたくさん転がっています。
WSL2をインストールしたら以下のコマンドを実行します。
sudo apt install python3 python3-pipこれだけやれば一見インストール方法のページに従うとできそうに思うのですが、実際に実行してみるとこんな感じになります。
$python3 -m pip install --user qmk
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
python3-xyz, where xyz is the package you are trying to
install.
If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
sure you have python3-full installed.
If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you. Make sure you have pipx installed.
See /usr/share/doc/python3.12/README.venv for more information.
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.とりあえず仮想環境を作ったらいいっぽいのでその指示に従いますが、WSL2はそこら辺のパッケージも入っていないのでひとまずコマンドを打つと親切に何をすればよいか教えてくれるのでその指示に従ってみます。
$python3 -m venv path/to/venv.
Then use path/to/venv/bin/pythonpython3 -m venv path/to/venv.
Then use path/to/venv/bin/python
The virtual environment was not created successfully because ensurepip is not
available. On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.
apt install python3.12-venv
You may need to use sudo with that command. After installing the python3-venv
package, recreate your virtual environment.私の環境だと書いてあるpython3.12-venvが正解らしいのでこれを入れておきます。
sudo apt install python3.12-venvあとは実際にvenvを作る必要があるので作ってactivateしてみます。今回はqmkという仮想環境を作ってみます。
python3 -m venv qmk
source qmk/bin/activateこれで仮想環境ができたのであとはqmkを入れるだけですが、ここでもチュートリアル通りのコマンドを打つとダメなので以下のコマンドを打ちます。
python3 -m pip install qmkあとは実際に環境を作成するsetupを実行します。
qmk setupインストール中に色々出てきますが、基本的には全てyを押して必要なものを導入していけば使えるようになります。インストールの最後の方に「Ψ QMK is ready to go」と表示されていればひとまずビルドができる環境になっているはずです。
実際に適当なキーボードのファームウェアを作成してみましょう。セットアップのページに載っているように以下のようにします。
qmk compile -kb clueboard/66/rev3 -km defaultこれで正しくビルドできていればqmkの環境構築は完了です。今まで仮想環境とかなくてもいけましたし、なんならPythonとかも使わないで行けたのですが、ひとまず執筆現在(2025/08/23)はこの方法でファームウェアをビルドできます。書き込みは無理してWSLでやる必要もないのでbinファイルだけQMK ToolBoxから書けばよいと思います。
以上です。お読みいただきありがとうございました。