WSL2環境構築｜Ubuntu開発環境をコマンドだけで整える手順

WSL2（Windows Subsystem for Linux 2）とは、Windows の中で本物の Linux カーネルを動かし、Ubuntu などの Linux 環境を使えるようにする仕組みです。 仮想マシンを自分で用意しなくても、wsl --install の1行で Linux の開発環境が手に入ります。

この記事では、Windows 側のコマンド（Microsoft Learn の公式手順に準拠）と、Ubuntu 側のセットアップコマンドを順番どおりに並べ、Ubuntu 24.04 で実際に実行した出力を載せました。さらに、公式ガイドの入口ページには載っていない .wslconfig と /etc/wsl.conf のコピペ用テンプレートと設定キー表、改行コード（CRLF）で実際に出るエラー文と直し方、VPN・メモリ・ファイルの置き場所などのつまずきチェックリストまでまとめています。

WSL2環境構築の早見表

全体の流れ

flowchart TD
    A[Windows: wsl --install] --> B[再起動・Ubuntu のユーザー作成]
    B --> C[Windows: wsl -l -v / wsl --update]
    C --> D[Ubuntu: apt 更新・基本ツール]
    D --> E[Ubuntu: Git 設定・SSH 鍵]
    E --> F[Ubuntu: Node（nvm）・Python（uv）]
    F --> G[Docker: Desktop 連携 or Engine]
    G --> H[Windows: .wslconfig / Ubuntu: wsl.conf]
    H --> I[VS Code: WSL 拡張で ~/ のフォルダを開く]

Windows 側の作業は最初と最後の設定だけで、あとは Ubuntu のターミナルで完結します。

Windows側の手順（Microsoft Learn準拠）

この章のコマンドは Microsoft Learn の「WSL のインストール」「WSL の基本的なコマンド」に沿って記載しています。検証環境に Windows 実機がないため、Windows 側のコマンドは未実行です（出力例は載せていません）。

1. WSLとUbuntuをインストールする

PowerShell を「管理者として実行」で開き、次を実行します。

wsl --install

既定では Ubuntu がインストールされます。 完了後に Windows を再起動すると Ubuntu が起動し、Linux 用のユーザー名とパスワードの入力を求められます。このパスワードは sudo で使うので控えておきます（Windows のパスワードとは別です）。

ほかのディストリや別バージョンを入れたいときは、一覧から名前を確認して指定します。

wsl -l -o                      # 入れられるディストリの一覧（--list --online）
wsl --install -d <ディストリ名>  # 一覧の NAME 列の値を指定

2. バージョンと状態を確認する

wsl -l -v        # インストール済みディストリと VERSION（2 になっているか）
wsl --status     # 既定のディストリ・既定のバージョン
wsl --version    # WSL 本体・カーネルのバージョン
wsl --update     # WSL 本体を最新に

VERSION が 1 のディストリがあれば、次のコマンドで WSL2 に変換できます。

wsl --set-version Ubuntu 2
wsl --set-default-version 2   # 今後入れるディストリを WSL2 に

3. ディストリを管理する（起動・停止・既定の変更）

4. バックアップと複製（export / import）

wsl --export で環境を1つのファイルに保存し、wsl --import で復元・複製できます。 大きな変更の前や、PC の移行時に便利です。

# 停止してからエクスポート（tar 形式）
wsl --shutdown
wsl --export Ubuntu D:\backup\ubuntu-2026-10-01.tar

# 別名で読み込む（複製して検証用に使うなど）
wsl --import Ubuntu-dev D:\wsl\Ubuntu-dev D:\backup\ubuntu-2026-10-01.tar

# VHD 形式でも出力できる
wsl --export Ubuntu D:\backup\ubuntu.vhdx --vhd

--import したディストリは、既定で root ユーザーで起動します。普段のユーザーで起動したいときは、後述の /etc/wsl.conf の [user] に default=ユーザー名 を書きます。

Ubuntu側のセットアップコマンド集（実行結果つき）

ここからは Ubuntu のターミナルで実行します。この章のコマンドは Ubuntu 24.04.4 LTS の Linux コンテナで実際に実行し、出力を載せています。 WSL 上の Ubuntu でも、パッケージやツールの動きは同じです（WSL 固有の部分は都度注記します）。

1. パッケージを更新して基本ツールを入れる

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git curl wget unzip zip ca-certificates jq dos2unix

インストール後のバージョン確認です。

git --version; gcc --version | head -1; jq --version; dos2unix --version | head -1

git version 2.43.0
gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
jq-1.7
dos2unix 7.5.1 (2023-08-29)

2. Gitの初期設定

git config --global user.name "Taro Yamada"
git config --global user.email "taro@example.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input
git config --global core.editor "code --wait"
git config --global --list

user.name=Taro Yamada
user.email=taro@example.com
init.defaultbranch=main
core.autocrlf=input
core.editor=code --wait

core.autocrlf input は「コミット時に CRLF を LF に変換し、チェックアウト時は変換しない」設定で、WSL 側の Git に向いています。Windows 側の Git と同じリポジトリを共有する場合は、後述の .gitattributes で改行コードを固定するとより確実です。

Windows の資格情報マネージャーを WSL から使う方法（Git for Windows の credential manager を指定する方法）も公式ガイドで紹介されています。HTTPS で認証する場合はそちらを、SSH で接続する場合は次の SSH 鍵を使います。

3. SSH鍵を作る（要点のみ）

ssh-keygen -t ed25519 -C "taro@example.com" -f ~/.ssh/id_ed25519 -N ""
ls -l ~/.ssh

実行結果（先頭部分。この後に指紋と randomart が表示されます）：

Created directory '/home/dev95/.ssh'.
Generating public/private ed25519 key pair.
Your identification has been saved in /home/dev95/.ssh/id_ed25519
Your public key has been saved in /home/dev95/.ssh/id_ed25519.pub
total 8
-rw------- 1 dev95 dev95 411 Oct  1 14:03 id_ed25519
-rw-r--r-- 1 dev95 dev95  98 Oct  1 14:03 id_ed25519.pub

ここでは確認のためパスフレーズなし（-N ""）で作りましたが、普段使う鍵はパスフレーズを設定するのがおすすめです。秘密鍵は WSL 側の ~/.ssh（権限 600）に置くと、Windows 側のフォルダに置いた場合のような権限の問題が起きません。GitHub への登録や Permission denied の対処は、別記事「SSH鍵の作成とGitHub接続」で詳しく解説しています。

4. Node.jsを入れる（nvm、要点のみ）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash

実行結果（末尾）：

=> Close and reopen your terminal to start using nvm or run the following to use it now:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

source ~/.bashrc
nvm --version      # => 0.40.8（実行結果）
nvm install --lts
node -v && npm -v

nvm 0.40.8 のインストールと ~/.bashrc への追記までは実行して確認しました。 Node 本体のダウンロード（nvm install --lts）は、検証環境から nodejs.org に接続できないため未実行です。nvm と fnm・mise・Volta の比較や、プロジェクトごとのバージョン固定は別記事「Node.js バージョン管理」で扱っています。

Ubuntu の apt で入る nodejs はバージョンが固定され更新が遅めなので、開発用にはバージョン管理ツール経由で入れると、Node のバージョンを切り替えやすくなります。

5. Pythonを入れる（uv、要点のみ）

uv の公式インストール方法はスクリプト（curl -LsSf https://astral.sh/uv/install.sh | sh）です。検証環境ではスクリプトの取得先に接続できないため、PyPI で配布されている同じ uv（0.12.19）を入れて確認しました。

uv --version
uv python install 3.13
mkdir -p ~/work && cd ~/work
uv init hello-wsl && cd hello-wsl
uv add requests
uv run python -c 'import sys,requests;print(sys.version.split()[0], requests.__version__)'

uv 0.12.19 (x86_64-unknown-linux-gnu)
Installed Python 3.13.15 in 1.84s
 + cpython-3.13.15-linux-x86_64-gnu (python3.13)
Initialized project `hello-wsl` at `/home/dev95/work/hello-wsl`
 + idna==3.20
 + requests==2.34.2
 + urllib3==2.8.0
3.13.15 2.34.2

Ubuntu 標準の python3 には手を加えず、uv が管理する Python をプロジェクトごとに使うので、システムの Python と競合しません。pip からの移行やチームでの使い方は別記事「uvの使い方」を参照してください。

6. Dockerを使えるようにする

WSL で Docker を使う方法は2つあります。

Docker Engine を直接入れる場合の手順です（Docker 公式ドキュメント「Install Docker Engine on Ubuntu」の apt リポジトリ方式に準拠。検証環境から download.docker.com に接続できないため未実行）。

# Docker の公式 GPG キーを追加
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
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

# リポジトリを追加
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update

# インストールと動作確認
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo docker run hello-world

# sudo なしで使う（ログインし直すと反映）
sudo usermod -aG docker $USER

Docker Desktop と Docker Engine を同じ Ubuntu で同時に使うと、どちらのデーモンにつながっているか分かりにくくなるので、どちらか一方に決めておくと迷いません。Docker のコマンドや Compose の書き方は既存の Docker 関連記事で詳しく扱っています。

.wslconfigと/etc/wsl.confのテンプレート

.wslconfig は WSL2 全体（VM）の設定、/etc/wsl.conf はディストリごとの設定です。設定キーと既定値は Microsoft Learn の「WSL での詳細設定の構成」で確認しました。

.wslconfig（コピペ用テンプレート）

# %UserProfile%\.wslconfig （例: C:\Users\taro\.wslconfig）
[wsl2]
# VM に割り当てるメモリ（既定: Windows のメモリの 50%）
memory=8GB
# 仮想 CPU 数（既定: Windows の論理プロセッサ数）
processors=4
# スワップ（既定: メモリの 25%）
swap=4GB
# Windows と同じネットワークを使う（Windows 11 22H2 以降）
networkingMode=mirrored
# DNS を Windows 経由で解決（Windows 11 22H2 以降、既定 true）
dnsTunneling=true
# Windows のプロキシ設定を引き継ぐ（Windows 11、既定 true）
autoProxy=true

[experimental]
# 使っていないキャッシュメモリを Windows に返す
autoMemoryReclaim=gradual
# 新しく作る仮想ディスクを自動で縮む形式にする
sparseVhd=true

メモリは「PC のメモリの半分を上限に、必要なら少し下げる」のが目安です。16GB の PC で Docker を使うなら memory=8GB 前後から始め、free -h で様子を見て調整します。

/etc/wsl.conf（コピペ用テンプレート）

# /etc/wsl.conf （sudo nano /etc/wsl.conf などで編集）
[boot]
# systemd を有効化（Docker Engine や systemctl を使う場合）
systemd=true

[user]
# 起動時のユーザー（wsl --import したディストリで便利）
default=taro

[automount]
enabled=true
root=/mnt/
# Windows ドライブのファイルにも Linux の権限情報を持たせる
options="metadata,umask=22,fmask=11"

[interop]
enabled=true
# Windows の PATH を Linux の PATH に追加しない（コマンド補完が速くなる）
appendWindowsPath=false

[network]
hostname=wsl-dev
generateHosts=true
generateResolvConf=true

appendWindowsPath=false にすると code . や explorer.exe が見つからなくなるので、必要なら ~/.bashrc に VS Code のパスだけ追加します（例：export PATH="$PATH:/mnt/c/Users/taro/AppData/Local/Programs/Microsoft VS Code/bin"）。

設定を反映させる

wsl --shutdown
wsl --list --running   # 何も表示されなければ停止済み

公式ドキュメントでは、すべてのシェルを閉じてから WSL が完全に止まるまで約8秒かかる「8秒ルール」が紹介されています。wsl --shutdown を使えばすぐに停止できます。

つまずきチェックリスト

改行コード（CRLF）で実際に出るエラーと直し方

Windows のエディタで作ったシェルスクリプトは、改行が CRLF（\r\n）になっていることがあります。Ubuntu 24.04 で CRLF のスクリプトを実行した結果です。

file deploy.sh
./deploy.sh; echo "exit=$?"
bash deploy.sh; echo "exit=$?"

deploy.sh: Bourne-Again shell script, ASCII text executable, with CRLF line terminators
-bash: line 4: ./deploy.sh: cannot execute: required file not found
exit=127
start
deploy.sh: line 3: cd: $'/tmp\r': No such file or directory
done
exit=0

./deploy.sh で実行すると「required file not found」になります。1行目の #!/bin/bash の末尾に \r が付き、/bin/bash\r というファイルを探してしまうためです。bash deploy.sh で実行すると動いてしまいますが、cd: $'/tmp\r' のように各行の末尾に \r が残り、終了コードは 0 のまま一部の処理が失敗しています。

dos2unix で LF に変換すると正しく動きます。

dos2unix deploy.sh
file deploy.sh
./deploy.sh

dos2unix: converting file deploy.sh to Unix format...
deploy.sh: Bourne-Again shell script, ASCII text executable
start
done

リポジトリ全体で改行コードをそろえるには、.gitattributes をコミットするのが確実です。

# .gitattributes
* text=auto eol=lf
*.sh text eol=lf
*.bat text eol=crlf

CRLF のファイルを git add したときの状態です（git ls-files --eol で、i/ はリポジトリ内、w/ は作業ツリーの改行）。

warning: in the working copy of 'crlf.sh', CRLF will be replaced by LF the next time Git touches it
i/lf    w/lf    attr/text=auto eol=lf   .gitattributes
i/lf    w/crlf  attr/text eol=lf        crlf.sh

リポジトリには LF で保存され（i/lf）、次にチェックアウトしたときに作業ツリーも LF になります。 VS Code 側でも "files.eol": "\n" を設定しておくと、新しく作るファイルが最初から LF になります。

VS Code で WSL の中を開く

1. Windows に VS Code をインストールし、拡張機能「WSL」（ms-vscode-remote.remote-wsl）を入れる
2. Ubuntu のターミナルで作業フォルダに移動し、code . を実行
3. 初回は WSL 側に VS Code Server が自動でインストールされる
4. 左下に「WSL: Ubuntu」と表示されていれば、拡張機能・ターミナル・デバッガーが Linux 側で動いている状態

Python や ESLint などの言語系の拡張機能は「WSL: Ubuntu にインストール」が必要です。拡張機能ビューで WSL 側にインストールされているか確認しましょう。

よくある質問

Q. WSL2 と Docker Desktop はどちらか一方だけでよいですか？ A. Docker Desktop は WSL2 を土台にして動くので、Docker Desktop を使う場合も WSL2 は必要です。WSL2 だけで Docker を使いたい場合は、Ubuntu に Docker Engine を直接入れる方法があります（systemd の有効化が必要）。

Q. ファイルは Windows 側と Linux 側、どちらに置けばよいですか？ A. Linux のツール（git、npm、python）で扱うファイルは Linux 側（~/）に置くのが基本です。Microsoft Learn でも、最高のパフォーマンスを得るには使うツールと同じファイルシステムに置くよう案内されています。Windows のアプリからは、エクスプローラーの「Linux」項目や \\wsl$\Ubuntu で開けます。

Q. .wslconfig を書いたのに反映されません。 A. ファイルの場所（%UserProfile% 直下、拡張子なしの .wslconfig）と、wsl --shutdown で WSL を完全に停止したかを確認してください。メモ帳で保存すると .wslconfig.txt になることがあるので、エクスプローラーで拡張子を表示して確認すると確実です。

Q. 環境を壊してしまったらどうすればよいですか？ A. 事前に wsl --export でバックアップしておけば、wsl --import で戻せます。まっさらにしたいときは wsl --unregister Ubuntu で削除してから wsl --install し直します（unregister は中のデータも削除されるので、必要なファイルを先に退避します）。

まとめ

• Windows 側は wsl --install → wsl -l -v → wsl --update の3つでほぼ完了。export / import でバックアップと複製ができる
• Ubuntu 側は apt 更新 → Git 設定 → SSH 鍵 → Node（nvm）→ Python（uv）→ Docker の順に、コマンドだけで整えられる
• .wslconfig は VM 全体（メモリ・CPU・ネットワーク）、/etc/wsl.conf はディストリごと（systemd・既定ユーザー・マウント）
• 設定の反映は wsl --shutdown。8秒ルールを覚えておくと迷わない
• 作業フォルダは ~/（Linux 側）に置くとファイル操作が速い
• CRLF のスクリプトは「required file not found」になる。dos2unix と .gitattributes で LF にそろえる
• VPN 環境では networkingMode=mirrored と dnsTunneling を試す

株式会社RJCでは、WSL2のような開発環境づくりのコツを仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。