WSL2 で Raspberry Pi 用 ARM64 開発環境を Docker で構築する方法（buildx 手動インストール対応・2025年12月版）

みなさん、こんにちは。

Raspberry Pi 向けのソフトウェア開発って楽しいけれど、いざ実機でコンパイルしたり環境構築したりするのは、意外と時間がかかって面倒ですよね。Windows 上で作業していても、「手軽に ARM64 の環境を再現したい」と思う場面は多いはずです。

そこで今回は、WSL2（Ubuntu 22.04）+ Docker + QEMU + buildx を使って、Raspberry Pi OS（Bullseye）互換の ARM64 開発環境を構築する手順をまとめました。

あえて Bullseye ベースにしているのは、既存プロジェクトの互換性を重視するためです。もし最新の Bookworm 等を使いたい場合は、適宜 Dockerfile を書き換えてみてくださいね。

　

　

はじめに – buildx の手動インストールについて

　

WSL2 (Ubuntu 22.04) の標準リポジトリで Docker を入れると、buildx プラグインが入っていなかったり、バージョンが古かったりすることがあります。 今回は、2025年12月現在の最新版 v0.30.1 を手動で導入し、確実にマルチプラットフォームビルドができる環境を整えます。

　

　

前提環境の準備

　

まずは WSL2 が動いていることを確認しましょう。

PowerShellで以下のコマンドを実行してください。

wsl --version

WSL バージョンで2系が表示されていれば問題ありません。

次に、WSL2 内（Ubuntu 22.04）に Docker と QEMU をインストールします。

Ubuntu 22.04 Terminalに入って以下コマンドを実行してください。

sudo apt update
sudo apt install -y docker.io qemu-user-static
sudo usermod -aG docker $USER

設定を反映させるため、一度 WSL を再起動します。exit でUbuntu 22.04 Terminal を抜けた後、PowerShellで以下のコマンドを実行してください。

wsl --shutdown

　

　

QEMU（ARM エミュレーション）の有効化

　

x86_64（Windows）上で ARM バイナリを動かすために、QEMU のエミュレーターを登録します。Ubuntu 22.04 Terminal に入って以下のコマンドを実行してください。

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

これで準備は OK です。

　

　

buildx プラグインの手動インストール（v0.30.1）

　

Ubuntu 22.04 でインストールした標準の Docker には buildx が入っていないので、手動でセットアップします。

[!NOTE] 2025年12月24日時点の最新版 v0.30.1 を使用します。将来バージョンが変わっている場合はGitHub Releasesを確認してください。

1. プラグインディレクトリを作成

mkdir -p ~/.docker/cli-plugins

2. buildx バイナリをダウンロード

curl -SL \
  https://github.com/docker/buildx/releases/download/v0.30.1/buildx-v0.30.1.linux-amd64 \
  -o ~/.docker/cli-plugins/docker-buildx

3. 実行権限を付与して動作確認

chmod +x ~/.docker/cli-plugins/docker-buildx
docker buildx version

無事にバージョンが表示されれば成功です！

　

　

Raspberry Pi OS 互換 Dockerfile の作成

　

作業ディレクトリを作成し、Dockerfile を用意します。

mkdir ~/rpi-bullseye
cd ~/rpi-bullseye

内容は以下の通りです。Dockerfileというファイル名で保存してください。

FROM arm64v8/debian:bullseye

ENV container docker

# 必要なパッケージのインストール
RUN apt update && \
    apt install -y systemd systemd-sysv sudo python3 python3-pip git curl bluez i2c-tools && \
    apt clean

# systemd 向けの停止信号設定
STOPSIGNAL SIGRTMIN+3

# systemd を起動
CMD ["/sbin/init"]

　

　

ARM64 イメージのビルド

　

buildx を使って、明示的に ARM64 アーキテクチャとしてビルドします。ターミナルで以下のコマンドを実行します。

# ビルダーの作成と切り替え
docker buildx create --name mybuilder
docker buildx use mybuilder
docker buildx inspect --bootstrap

# ARM64 イメージとしてビルド
docker buildx build \
  --platform linux/arm64 \
  -t rpi-bullseye-systemd \
  --load \
  .

ビルドが終わったら、イメージができているか確認しましょう。

docker images | grep rpi-bullseye-systemd

REPOSITORY 列に rpi-bullseye-systemd と表示されていたら成功です。

　

　

systemd が動くコンテナの起動

　

Raspberry Pi のサービス（systemd）をシミュレートするため、いくつかのオプションを付けて起動します。ターミナルで以下のコマンドを実行してください。

docker run --privileged -d \
  --name rpi-bullseye \
  --platform linux/arm64 \
  --cgroupns=host \
  -v /sys/fs/cgroup:/sys/fs/cgroup \
  rpi-bullseye-systemd

英数字の羅列が表示され、コンテナが起動するはずです。

コンテナが起動したあと、本当にバックグラウンドで動き続けているかを確認しましょう。

docker ps

このコマンドを叩いて、NAMES 列に rpi-bullseye が表示されていれば成功です！もし表示されない場合は、起動直後にエラーで落ちている可能性があるため、docker ps -a で停止中のコンテナを含めて確認してみてください。

　

　

開発時の基本操作

　

コンテナが起動したら、あとは自由に入って作業するだけです。

  • コンテナに入る
docker exec -it rpi-bullseye bash
  • 停止・再開
docker stop rpi-bullseye
docker start rpi-bullseye

注意 – WSL2再起動後の「exec format error」対策

WSL2は軽量な仮想マシン（VM）であるため、Windowsの再起動などでWSL2自体も再起動すると、以前登録した binfmt_misc（QEMUの設定）が初期化されてしまう ことがあります。

この状態で docker start しようとすると、“exec format error” というエラーが出てコンテナが起動しません。

毎回コマンドを打ち直すのは面倒なので、QEMUを再登録する簡単なスクリプトを作っておきましょう。

1. スクリプトの作成
vi ~/rpi-bullseye/qemu-register.sh
2. 以下の内容を入力して保存
#!/bin/bash

# QEMU が登録されているか確認
if ! grep -q "qemu-aarch64" /proc/sys/fs/binfmt_misc/qemu-aarch64 2>/dev/null; then
    echo "Registering QEMU for ARM64..."
    docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
else
    echo "QEMU for ARM64 is already registered."
fi
3. 実行権限の付与
chmod +x ~/rpi-bullseye/qemu-register.sh

今後、WSL2を立ち上げた直後やエラーが出た際は、docker start の前にこのスクリプトを実行してください。これでスムーズに開発環境へ復帰できるようになります。

　

　

コンテナ内での環境整備（Tips）

　

コンテナに入った後、よく使うツールやタイムゾーンを設定しておくと便利です。

# パッケージ追加
apt update && apt install -y procps iproute2 iputils-ping nano less

# タイムゾーン変更（日本時間にする場合）
dpkg-reconfigure tzdata

# Python ライブラリの追加
pip3 install <package_name>

　

　

環境のクリーンアップとリセット

　

もし Dockerfile を書き換えて環境を作り直したい場合は、以下の手順でリセットできます。

コンテナ停止＆削除

docker stop rpi-bullseye && docker rm rpi-bullseye

イメージ削除

docker rmi rpi-bullseye-systemd

未使用リソースの一括削除

docker container prune # 停止中コンテナを削除
docker image prune -a # 未使用イメージを削除

　

　

まとめ

　

これで WSL2 上に Raspberry Pi OS（Bullseye）互換の ARM64 開発環境 が整いました。

今回のポイントは以下の3点です。

  1. WSL2 で最新の buildx を手動インストールしてビルド環境を安定させる。
  2. buildx + QEMU を活用して ARM64 イメージを生成する。
  3. systemd を動かすために起動オプション（--privileged 等）を適切に設定する。

この環境があれば、実機が手元になくてもコードを書いてビルド・テストが完結できます。

ぜひみなさんも活用してみてください。

　

本日も最後までお読みいただきありがとうございました。

それでは、よい Raspberry Pi ライフを！

関連投稿

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール