WSL2・Docker セットアップ詳細（Windows 向け）

このページは、Windows 受講生向けに WSL2 と Docker のセットアップ手順を詳細に解説するものである。環境構築クイックスタート（macOS / Windows）で詰まった場合や、Docker Desktop / WSL ネイティブ Docker の選択・トラブル対処の詳細を確認したいときに参照する。macOS 利用者はこのページを読む必要はない。

開発作業は原則として WSL2 上の Ubuntu ターミナルで行う。PowerShell やコマンドプロンプトは WSL の管理用コマンドを実行するときにだけ使う、という役割分担を最初に押さえておく。

WSL2 のインストール

1. Windows ターミナルを開く

スタートメニューで「ターミナル」を検索して起動する。規定ではコマンドプロンプトまたは PowerShell のタブが開くので、どちらでも構わない（以降の wsl コマンドは両方で動作する）。

2. `wsl --install` を実行する

wsl --install

これだけで WSL2 本体と既定ディストリである Ubuntu が同時にインストールされる。完了後、PC を再起動する必要がある場合がある。

3. 既定ディストリが Ubuntu になっているか確認する

再起動後、再びターミナルを開いてコマンドプロンプトのタブで以下を実行する。

wsl -l

出力例:

Linux 用 Windows サブシステム ディストリビューション:
Ubuntu-24.04 (既定値)
docker-desktop

Ubuntu-24.04 (既定値) と表示されていれば問題ない。Ubuntu が既定値になっていない場合は、次のコマンドで既定に設定する。

wsl -s Ubuntu-24.04

この操作を正しく終了しました と表示されたら、もう一度 wsl -l で既定値が切り替わっていることを確認する。

4. 初回起動でユーザー名・パスワードを設定する

Ubuntu を初めて起動するとユーザー名とパスワードの入力を求められる。どちらも後続の作業で sudo を使うたびに必要になるため、パスワードは必ずメモに残しておく。Windows アカウントのパスワードとは別物で、Ubuntu 内だけで通用する資格情報である。

入力タイミングは Windows / WSL のバージョンによって異なる。wsl --install 直後に聞かれる場合もあれば、ディストリの初回起動時に聞かれる場合もある。

5. Windows Terminal のデフォルトを Ubuntu に切り替える

Windows Terminal のタブ横にある ∨ を押し、設定画面を開く。既定のプロファイル を Ubuntu に変更すると、以降はターミナルを起動するだけで WSL が立ち上がる状態になる。

WSL のパスワード再設定方法

Ubuntu のパスワードを忘れると sudo が打てず、パッケージインストールもできなくなる。次の手順で root 経由で再設定する。

1. コマンドプロンプトから root でログインする

Windows 側のコマンドプロンプト（または PowerShell）で以下を実行する。

wsl -u root

プロンプトが root@ホスト名:~# のような形に変われば root でログインできている。

2. 対象ユーザー名を確認する

まず root ログイン中にユーザー名が分からない場合は、別タブで Ubuntu を普通に開き、次を実行する。

whoami

出力された文字列がパスワードを再設定するユーザーの名前である。

3. `passwd` で再設定する

root シェルに戻り、ユーザー名を指定して新しいパスワードを入力する。

passwd <ユーザー名>

New password: と Retype new password: を入力すれば完了。以降は通常ユーザーに戻って sudo が使えることを確認する。

Docker のインストール：2 つの選択肢

Windows で Docker を使う方法は大きく 2 通りある。

方式	メリット	デメリット
Docker Desktop for Windows	GUI 付きで導入が簡単。Kubernetes や Extensions も使える	PC によっては常駐時に動作が重くなる。商用利用ではライセンス料が発生する場合がある
WSL ネイティブ Docker（Docker CE）	軽量。ライセンスの影響を受けない	コマンド操作に慣れる必要がある。サービス起動は毎回手動になる

最初は Docker Desktop で始め、動作が重いと感じたら WSL ネイティブへ切り替える方針で問題ない。

Docker Desktop を使う場合

1. インストーラーを取得する

Docker Desktop for Windows にアクセスし、Docker Desktop for Windows - x86_64 をダウンロードする。RUNTEQ カリキュラムでは Arm アーキテクチャの Windows PC は非推奨のため、x86_64 版を選ぶ。

2. インストーラーを起動する

ダウンロードしたファイルをダブルクリックし、インストーラーの指示にそのまま従う。完了後 Close and restart をクリックして PC を再起動する。

3. WSL 統合を有効化する

再起動後、Docker Desktop を起動する。右上の歯車アイコンから設定画面を開き、以下を有効化する。

Resources → WSL Integration → Enable integration with my default WSL distro
同画面の Enable integration with additional distros で Ubuntu のトグルを ON
Apply & restart で設定を保存

4. Ubuntu 側で動作確認する

Ubuntu ターミナルで次を実行する。

docker -v

Docker version 27.x.x, build ... のようにバージョンが表示されれば、WSL から Docker Desktop のデーモンへアクセスできている。バージョンが出ず command not found や接続エラーになる場合は、Docker Desktop 本体が起動しているか・WSL Integration で Ubuntu が ON になっているかを見直す。

Docker Desktop を使わない場合（WSL ネイティブ Docker）

Docker Desktop をインストール済みでこの方式に切り替える場合は、先に Docker Desktop を停止する。以下はすべて Ubuntu ターミナルで実行する。

1. 古いパッケージを削除する

sudo apt-get remove docker docker-engine docker.io containerd runc

2. リポジトリ取得に必要なパッケージを入れる

sudo apt-get update
sudo apt-get -y install ca-certificates curl gnupg lsb-release

3. GPG キーを追加する

公式キーを取り込むことで、後続の apt リポジトリが正当かどうかを検証できるようになる。

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

4. Docker 用 apt リポジトリを設定する

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. Docker 本体をインストールする

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose

6. Docker デーモンを起動する

WSL の Ubuntu は systemd が標準で有効でない構成もあり得るため、service コマンドでデーモンを起こすのが確実である。

sudo service docker start

Ubuntu を再起動（wsl --shutdown → 再ログイン）するたびに再度実行が必要になる点に注意する。常駐させたい場合は /etc/wsl.conf に [boot] systemd=true を追記して systemd を有効化する方法もある。

7. 動作確認（docker-compose）

カリキュラムで docker compose up が登場する場面ではあえて docker-compose（ハイフン区切り） を使う。Docker CE と同時に入れた docker-compose パッケージが独立バイナリとして動くためである。

docker-compose up

8. `docker-credential-desktop.exe` エラーへの対処

以下のようなエラーが出る場合、以前インストールした Docker Desktop の資格情報ヘルパー設定が残っている。

"docker-credential-desktop.exe": executable file not found in $PATH, out: ``

~/.docker/config.json を開き、credsStore を credStore に変更して保存すれば解消する。

{
  "credStore": "desktop.exe"
}

Docker 生成ファイルで Permission Denied が出るとき

Rails などを Docker コンテナ内で動かしているとき、bin/rails generate model User のようにコンテナ側でファイルを生成すると、ホストの VSCode で編集できなくなる（Permission Denied）ことがある。

対処はシンプルで、プロジェクトルートで次を実行し、所有者を自分に戻す。

sudo chown -R $USER:$USER .

毎回のファイル生成後に実行する運用になるが、WSL2 環境では避けにくい作業コストと割り切る。

なぜ WSL2 ではファイル権限の問題が起きやすいのか

卒業までに細部まで理解する必要はないが、原因を一度押さえておくと納得感が違う。

ユーザー識別子の違い: Linux は UID/GID で、Windows は SID でユーザーを表現する。WSL2 は両者を橋渡しする必要があり、境界でズレが生じやすい。
ファイルシステムのエミュレーション: WSL2 は Windows のディスク上に Linux のファイルシステムをエミュレートしている。所有権やパーミッションのメタデータが完全には一致せず、コンテナとホストの往復で不整合が発生する。
macOS は Unix 系: macOS のファイルシステムはもともと Unix 系で UID/GID をそのまま扱う。Docker コンテナとホスト間で権限が揃いやすいため、同種の問題は顕在化しにくい。

Windows で開発する以上、ファイル生成後の chown はセットで覚えておく。

参考リソース

WSL インストールガイド（Microsoft 公式）: https://learn.microsoft.com/ja-jp/windows/wsl/install
Docker Desktop for Windows: https://docs.docker.com/desktop/install/windows-install/
Docker CE on Ubuntu: https://docs.docker.com/engine/install/ubuntu/
WSL 上で systemd を有効化する: https://learn.microsoft.com/ja-jp/windows/wsl/systemd

確認クイズ

Q1. WSL2 の既定ディストリを確認するコマンドは次のうちどれか。　A. wsl --version　B. wsl -l　C. wsl status　D. wsl show

正解: B. wsl -l

解説: wsl -l（または wsl --list）でインストール済みディストリと既定値を確認できる。既定を切り替えるときは wsl -s <ディストリ名> を使う。

Q2. Ubuntu のパスワードを忘れた場合、最初に実行すべきコマンドは何か。

正解: コマンドプロンプトで wsl -u root を実行し、root としてログインする。

解説: root でログインすれば passwd <ユーザー名> で任意のユーザーのパスワードを書き換えられる。Windows 側のコマンドプロンプトから実行するのがポイントで、Ubuntu 側で sudo passwd を打とうにもそもそも sudo に旧パスワードが必要なので詰んでしまう。

Q3. Docker Desktop で Ubuntu を WSL に統合する設定はどこで行うか。

正解: Settings → Resources → WSL Integration で Ubuntu のトグルを ON にし、Apply & restart を押す。

解説: この設定を忘れると、Windows 側で Docker Desktop が動いていても WSL の Ubuntu から docker コマンドが通らない。

Q4. WSL ネイティブの Docker で docker-compose up を実行する前に、毎回必要になる手順は何か。

正解: sudo service docker start で Docker デーモンを起動する。

解説: WSL2 の Ubuntu は既定では systemd が無効なため、デーモンが自動起動しない。毎回 service コマンドで手動起動するか、/etc/wsl.conf に [boot] systemd=true を書いて systemd を有効にする。

Q5. コンテナ内で生成したファイルがホストの VSCode で編集できないとき、どのコマンドで解消するか。

正解: プロジェクトルートで sudo chown -R $USER:$USER . を実行する。

解説: コンテナ内の root ユーザーで作られたファイルは、ホスト側の一般ユーザーでは書き込み権限が無い状態になる。所有者を自分に戻すことで VSCode から編集できるようになる。

Q6. WSL2 で Docker 関連の権限問題が macOS より起きやすいのはなぜか。

正解: Windows（SID）と Linux（UID/GID）でユーザー識別方式が異なり、WSL2 がその差を橋渡ししているため、境界でメタデータの不整合が出やすいから。

解説: macOS はもともと Unix 系で UID/GID をそのまま扱うため、Docker コンテナとホスト間で権限の一貫性が保たれやすい。WSL2 ではこの前提が崩れるため、chown などの追加作業が必要になる場面が増える。

Q7. docker-credential-desktop.exe が見つからないエラーはどう直すか。

正解: ~/.docker/config.json の credsStore を credStore に書き換える。

解説: Docker Desktop をアンインストールした後もこの設定が残っていると、Docker CE が存在しない資格情報ヘルパーを呼び出そうとして失敗する。表記を credStore に変えると、デフォルトの資格情報ストアにフォールバックする。

生きているコード

本ドキュメントで扱ったパターンの完全な動作コードは、メンター側リポジトリの参照ブランチで確認できます。

対応 Week: W3
参照ブランチ:
W3: reference/week-3
対応 checklist 項目: （直接対応なし）

ブランチの作り方・見方は b00-curriculum-map を参照してください。