Windowsマシン上で本格的にLinux環境での開発を行うためにWSL2を学びながら構築してみました。

WSLの存在は昔から知ってはいたのですが、基本的にMac端末で開発することが多く、あえてWindowsマシンでLinux環境を使うことも使いたくなることもなかったのですが、

新しく参画したプロジェクトで、Windowsマシンで開発できる環境を構築する必要があり、その手段としてWSL2を導入することとなりました。

ということで、WSL2の仕組みや設定方法など一からキャッチアップしたので、学んだことを整理しておきます。

インストール環境

今回、環境構築に使用したWindowマシンは下記となります。

Windows 11 Pro 24H2

WSL2とは

まずはWSL2とはなんぞやについて簡単に。

WSLとはWindows Subsystem for Linuxの略で、Windowsマシンで仮想的なLinux環境を構築・実行できるものです。

WSL2では、仮想化の仕組みを活用し、仮想マシン（VM）内でLinuxカーネルが実行できます。

WSL環境構築の流れ

では、実際にWSL2環境を構築していきたいと思います。

WSLコマンドのインストール

PowerShell またはコマンドプロンプトを管理者モードで開きwsl --install コマンドを実行することでWSLをインストールしましょう。

今回インストールするLinuxディストリビューションはUbuntuとします。

// WSLコマンドのインストール
$ wsl --install

ダウンロード中: Linux 用 Windows サブシステム 2.4.13
インストール中: Linux 用 Windows サブシステム 2.4.13
Linux 用 Windows サブシステム 2.4.13 はインストールされました。
この操作を正しく終了しました。
ダウンロード中: Ubuntu
インストール中: Ubuntu
ディストリビューションが正常にインストールされました。'wsl.exe -d Ubuntu' を使用して起動できます

// 正常にインストールできたか確認
$ wsl -l -v
  NAME      STATE           VERSION
* Ubuntu    Stopped         2

wsl --installコマンドは「Windows 10 バージョン 2004 以上 (ビルド 19041 以上)」または「Windows 11」で有効であり、Windowsの古いビルドを実行している場合は、"Linux 用 Windows サブシステム" オプション機能を有効にする必要があります。

以前のバージョンの WSL の手動インストール手順

wsl --installを実行するとLinuxディストリビューションは標準でUbuntuがインストールされます。もし指定のLinuxディストリビューションをインストールしたい場合は、-dオプションでLinuxディストリビューションを指定することもできます。

// 指定可能なLinuxディストリビューションをオンラインで確認
$ wsl --list --online

// `-d`オプションでLinuxディストリビューションを指定し実行
$ wsl --install -d <Distribution Name>

これでWSLの導入は完了となります。楽ちんですね。

昔は「Linux 用 Windows サブシステム」オプション機能を有効にするなどちょっと面倒だったのですが、コマンド一発でインストールできるようになったのは便利です。

よく使うWSLコマンド

WSLインストールした後によく使うコマンドについてもまとめておきます。

WSLコマンドのアップデート

$ wsl --update

WSLの起動状態確認

$ wsl --status

WSLのシャットダウン

$ wsl --shutdown

インストールされているWSLディストリビューションの一覧を表示

$ wsl --list --verbose

WSLの起動

$ wsl -d Ubuntu

Linux環境設定

WSLでの開発を行うために最低限必要な設定やソフトのインストール（Linux、Git、Docker）を実施します。

Linuxユーザー登録

WSLのインストールが完了したらスタートメニューから「Ubuntu」を選択し起動しましょう。

初回起動の場合、デフォルトユーザーの作成を促されるので作成します。

Provisioning the new WSL instance Ubuntu
This might take a while...
Create a default Unix user account: default_user ← ★ユーザー名を入力
New password:                                    ← ★パスワードを入力
Retype new password:                             ← ★パスワード（確認用）を入力
passwd: password updated successfully
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

Welcome to Ubuntu 24.04.2 LTS (GNU/Linux 5.15.167.4-microsoft-standard-WSL2 x86_64)

（以下、省略）

ここで入力するユーザー名やパスワードはLinux ディストリビューションごとに固有であり、Windows ユーザー名とは関係ないので、任意のもので問題ありません。また、ここで設定したユーザーが既定のユーザーとなり、以後起動時にはこのユーザーで自動的にサインインされます。

「Welcome to Ubuntu ～」と表示されればユーザー作成完了です。

APTパッケージの更新とアップグレード

Linuxへログインできたら、UbuntuのAPTパッケージの更新とアップグレードを行っておきましょう。

$ sudo apt update && sudo apt upgrade

Gitのインストール

WSL環境で開発作業を行うに当たり、ローカルリポジトリはWSL内のLinuxファイルシステムに作成することがおすすめとなります。

ホスト側（Windowsマシン）のリポジトリをWSL環境から参照できるようマウントすることでも可能ですが、ファイルの読み書きが非常に遅くパフォーマンスが悪くなってしまします。

そのため、WSL環境にGitをインストールし、リポジトリをWSL内にクローンできるようにする方法が一般的です。

WSLのLinuxにログインしsudo apt-get install gitコマンドを実行しGitをインストールします。

// Gitのインストール
$ sudo apt-get install git
[sudo] password for default_user:           ← ★パスワードを入力
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
git is already the newest version (1:2.43.0-1ubuntu7.2).
git set to manually installed.
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.

// ユーザー設定
$ git config --global user.name "Your Name"
$ git config --global user.email "youremail@domain.com"

// ユーザー設定の確認
$ git config --list
user.name="Your Name"
user.email="youremail@domain.com"

"Your Name"や"youremail@domain.com"にはご自身のGitHub「ユーザー名」と「メールアドレス」を入力してください。

これで、下記のようにWSL内でGitHubからリポジトリをクローンできるようになります。

$ mkdir ~/repo
$ cd ~/repo/

$ git clone https://github.com/mattwojo/helloworld-django.git

$ cd helloworld-django
$ code .

Git Credential Manager の設定

Git 資格情報ヘルパーであるGCMの設定を行っておきます。

GitHubの認証をアクセストークンなど別の方法で行いたい場合は、本手順を行う必要はありません。

$ git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

Dockerエンジンのインストール

WSL上でDockerコンテナでの開発をしたいので、Dockerエンジンをインストールします。

// Docker の公開鍵やスクリプトを HTTPS で取得するために必要なコマンドのインストール
$ sudo apt-get install ca-certificates curl

// APT 用 GPG 鍵の保存ディレクトリを作成
$ sudo install -m 0755 -d /etc/apt/keyrings

// Docker の GPG 公開鍵をダウンロードし、読み取り可能にする
$ sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc

// Docker リポジトリを APT に追加し、パッケージ一覧を更新
$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

// Docker パッケージを公式の APT リポジトリからインストールできるようにする
$ sudo apt-get update

// dockerのインストール
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

//イメージを実行してインストールが成功したことを確認
$ sudo docker run hello-world

また、ユーザー登録でUbuntuに作成したユーザー（default_user）で、dockerコマンドを実行するには通常sudoを頭に付ける必要がありますが、毎回つけるのは面倒なのでsudoをつけなくて良きようdockerグループにユーザーを追加しておきます。

// 現在のユーザーを`docker`グループに追加
$ sudo usermod -aG docker $USER

// WSLを再起動しグループ変更を反映
$ wsl --shutdown

// 動作確認（`sudo`なし）
$ docker run hello-world

これで、WSL2で最低限開発を始められるLinux環境の設定が完了となります。

WSL環境でのおすすめ開発統合環境

実際に、WSL環境で開発作業を行うにあたり「VSCode + Docker 拡張機能 + WSL 拡張機能 + Dev-Containers 拡張機能」構成での開発がおすすめとなります。

そのため、開発統合環境（IDE）に特にこだわりがない方は、VSCodeをインストールし「Docker 拡張機能」「WSL 拡張機能」「Dev-Containers 拡張機能」をインストールしましょう。

簡単にそれぞれの拡張機能の特徴を説明すると、

Decoker 拡張機能を使うことで、VS Code の内部からコンテナー化されたアプリケーションをビルド、管理、デプロイする機能が追加されます。
WSL 拡張機能を使うことで、通常のWindowマシンでの開発体験と同じ感覚でWSL上でも行うことができ、また、VSCodeの拡張機能もホスト（Windowsマシン）側とリモート側（WSL環境）で分けて管理をすることができ、Windowマシン側の環境を汚すことなく開発することができます。
Dev-Containers 拡張機能を使うことで、これまた通常のWindowマシンでの開発体験と同じ感覚でコンテナ上で開発を行うことができます。また、開発で使用するツール類（例えば、AWS CLIやNode.js等）もコンテナとして実行できる仕組みがあり、これはめちゃくちゃ便利です。

詳しくは別途記事にしようかと考えています。

以上