WSL トラブル回避ガイド
WSL よく使う設定の記録
ネットワークモード
WSL 2 の主なネットワークモードは、NAT と mirrored の 2 つです。デフォルトでは、WSL 2 は NAT モードを使います。
Mirrored
mirrored は、その名の通りネットワークをミラーリングするモードです。有効にすると、WSL は Windows のネットワークインターフェースを可能な限り複製し、WSL と Windows がより近いネットワーク環境で動作するようになります。
体感としては、次のようなメリットがあります。
- WSL と Windows のネットワークの挙動がより近くなる
- WSL から Windows 側のネットワーク環境をより手軽に利用できる
- VPN、社内プロキシ、ネットワークポリシーといった複雑なネットワーク環境下で、互換性が高まることが多い
主な利点は以下のとおりです。
- IPv6 のサポート
- WSL 内から
127.0.0.1で Windows 上のリッスンしているサービスにアクセス可能 - VPN との親和性が向上
- マルチキャストのサポート
- LAN 内の他のデバイスから、WSL で動作するサービスへより直接的にアクセス可能
注意点として、mirrored を利用するには Windows 11 22H2 以降が必要です。システムバージョンが古い場合、設定を記述しても反映されない可能性があります。
NAT
NAT は WSL 2 のデフォルトのネットワークモードです。
このモードでは、Windows ホストがルーターの役割を果たし、WSL は独立した仮想ネットワークセグメント内で動作します。
典型的な特徴は以下のとおりです。
- WSL 内部には
172.x.x.xや20.x.x.xといった独立したプライベート IP が割り当てられる - WSL から外部ネットワークへの接続は通常問題なく行える
- 外部デバイスから WSL のサービスにアクセスするには、通常ポートフォワーディングの設定が別途必要
- Windows ホストは
localhost:PORTで WSL のリッスンしているポートにアクセス可能
NAT モードで、WSL 内のプログラムがポートをリッスンしており、かつ localhostForwarding が無効化されていない場合、通常 Windows から同じポート番号の localhost でそのサービスにアクセスできます。
例えば、WSL で Web サーバーを起動したとします。
python3 -m http.server 3000
この場合、Windows 側からは通常以下の URL でアクセスできます。
http://localhost:3000
LAN 内の他のデバイスから WSL のサービスにアクセスさせたい場合は、通常ポートフォワーディングを設定するか、mirrored ネットワークモードに切り替える必要があります。
ファイルシステム
Windows のドライブは、WSL の /mnt ディレクトリにマウントされます。
C:→/mnt/cD:→/mnt/d
WSL のディストリビューションもまた、Windows から UNC パスとして参照できます。例えば、Ubuntu の Linux ファイルシステムのルート / は、通常以下のパスでアクセスできます。
\\wsl$\Ubuntu\
新しいバージョンの Windows では、次のようなパスも見られるかもしれません。
\\wsl.localhost\Ubuntu\
一般的な推奨事項は次のとおりです。
- Linux のコマンドラインで作業するなら、プロジェクトファイルは WSL の Linux ファイルシステム内に置く
- Windows のツールで作業するなら、プロジェクトファイルは Windows のファイルシステム内に置く
- プロジェクトファイルを、ファイルシステムをまたいで頻繁に読み書きするのは極力避ける
例えば、WSL で Node.js、Go、Rust、Python のプロジェクトを開発する場合、プロジェクトの配置場所として推奨されるのは以下のようなパスです。
/home/<ユーザー名>/projects
以下のようなパスではありません。
/mnt/c/Users/<ユーザー名>/Desktop
こうすることで、通常、パーミッション、パフォーマンス、ファイル監視まわりの問題を減らせます。
環境変数と相互運用
WSL は起動時に、Windows の環境変数の一部、特に Path を注入します。
デフォルトでは、WSL は Windows の Path を /mnt 形式のパスに変換し、Linux の $PATH に追加します。そのため、WSL 内で一部の Windows プログラムを直接呼び出せます。
例えば、以下のような操作が可能です。
notepad.exe
explorer.exe .
code .
WSL は Windows の .exe プログラムを直接実行することもできます。ほとんどの場合、WSL は Linux のパスと Windows のパスを自動的に相互変換します。
例えば、WSL で以下を実行すると、
explorer.exe .
現在のディレクトリを Windows のエクスプローラーで直接開けます。
ただし、相互運用機能や Windows Path の注入を無効にしていると、これらの動作は影響を受けます。
設定ファイル
WSL の設定ファイルは主に 2 種類あります。
- Windows 側のグローバル設定ファイル:
C:\Users<ユーザー名>.wslconfig - WSL ディストリビューション内部の設定ファイル:
/etc/wsl.conf
これらは適用範囲が異なります。
.wslconfig はすべての WSL 2 ディストリビューションに影響し、主に WSL 2 仮想マシン自体の設定（ネットワークモード、メモリ、CPU、プロキシ、ポートフォワーディングなど）に使います。
/etc/wsl.conf は現在のディストリビューションにのみ影響し、主にその Linux ディストリビューションの動作（デフォルトユーザー、Windows ドライブのマウント有無、systemd の有効化、Windows プログラムの呼び出し許可など）を設定するために使います。
Windows 側の設定: .wslconfig
.wslconfig は Windows のユーザーディレクトリ直下にあります。
C:\Users\<ユーザー名>\.wslconfig
よく使われる設定例です。
[wsl2]
networkingMode=mirrored
autoProxy=true
localhostForwarding=false
networkingMode
networkingMode は WSL 2 のネットワークモードを設定します。
一般的な値は以下のとおりです。
networkingMode=nat
または
networkingMode=mirrored
それぞれの意味は次のとおりです。
natはデフォルトモードmirroredはミラーネットワークモードbridgedは現在非推奨
VPN、LAN アクセス、IPv6、マルチキャストのサポートを改善したい場合は、以下を試してみてください。
networkingMode=mirrored
autoProxy
autoProxy は、Windows の HTTP プロキシ情報を自動的に WSL へ注入するかどうかを制御します。
例:
autoProxy=true
Windows でシステムプロキシが設定されている場合、これを有効にすると WSL は自動的にそのプロキシ情報を使おうとします。
ただし、使用しているプロキシソフトウェアが Windows ローカルの 127.0.0.1 のみをリッスンしている場合、NAT モードでは WSL がそのプロキシを直接利用できない問題が発生することがあります。これは、WSL 内の 127.0.0.1 が Windows ホストではなく、WSL 自身を指すためです。
このような場合の対応策としては、以下が考えられます。
autoProxyを無効にして、手動でプロキシアドレスを設定する- プロキシアドレスを、WSL からアクセス可能な Windows ホストのアドレスに変更する
- プロキシソフトウェア側で LAN 接続を許可する
- プロキシソフトウェアの TUN モードを使う
mirroredネットワークモードに切り替える
localhostForwarding
localhostForwarding は、WSL 2 でリッスンしているポートに、Windows ホストの localhost:PORT からアクセスできるかどうかを制御します。
例:
localhostForwarding=true
これはデフォルトで有効です。
NAT モードで、WSL 内で以下のようにサービスを起動し、
npm run dev
次のアドレスでリッスンしているとします。
0.0.0.0:3000
または
127.0.0.1:3000
この場合、Windows からは通常以下のアドレスでアクセスできます。
http://localhost:3000
もし以下のように設定すると、
localhostForwarding=false
Windows が localhost 経由で WSL のサービスにアクセスする機能は動作しなくなる可能性があります。
注意点として、mirrored モードでは localhostForwarding の設定は無視されます。
WSL 側の設定: /etc/wsl.conf
/etc/wsl.conf は WSL ディストリビューション内部にあります。
/etc/wsl.conf
よく使われる設定例です。
[boot]
systemd=true
[user]
default=ruqiu
[interop]
enabled=false
appendWindowsPath=false
[automount]
enabled=true
root=/mnt
boot.systemd
boot.systemd は systemd を有効にするかどうかを設定します。
[boot]
systemd=true
有効にすると、WSL 起動時に systemd が PID 1 として使われます。これにより、通常の Linux ディストリビューションに近い使用感が得られ、systemd に依存するサービスも利用しやすくなります。
例えば、以下のようなコマンドが使えます。
systemctl status
systemd を有効にすると、systemctl 関連の多くのコマンドを正常に使えるようになります。
ただし、systemd を有効にすると、最小構成のモードと比べて WSL の起動がわずかに遅くなる場合があります。
user.default
user.default はデフォルトのログインユーザーを設定します。
[user]
default=ruqiu
設定後、Windows から直接その WSL ディストリビューションを開くと、デフォルトで ruqiu ユーザーでログインします。
これはおおむね以下のコマンドと同等です。
wsl -u ruqiu
設定しない場合、WSL は通常、ディストリビューションの初回初期化時に作成されたユーザーを使います。
interop.enabled
interop.enabled は WSL と Windows 間の相互運用機能を制御します。
[interop]
enabled=false
無効にすると、WSL 内から Windows の .exe プログラムを直接呼び出せなくなります。
例えば、以下のコマンドは動作しなくなる可能性があります。
notepad.exe
explorer.exe .
code .
WSL から Windows プログラムを呼び出したくない場合は、これを無効にします。
interop.appendWindowsPath
interop.appendWindowsPath は、Windows の Path を WSL の $PATH に注入するかどうかを制御します。
[interop]
appendWindowsPath=false
無効にすると、Windows の PATH は WSL に自動追加されなくなります。
注意すべき点として、enabled と appendWindowsPath は別の設定です。
たとえ以下のように設定していても、
enabled=true
もし以下のように設定されていると、
appendWindowsPath=false
WSL は依然として Windows プログラムの呼び出しをサポートしますが、PATH を頼りにこれらの .exe を自動検出することはできなくなります。この場合、フルパスを手動で指定する必要があります。
automount.enabled
automount.enabled は Windows ドライブを自動マウントするかどうかを制御します。
[automount]
enabled=true
デフォルトでは、Windows ドライブは /mnt 以下に自動マウントされます。
例:
/mnt/c
/mnt/d
もし以下のように設定すると、
[automount]
enabled=false
Windows ドライブは WSL に自動マウントされなくなります。
ただし、これは Windows ドライブが WSL 内部にマウントされるかどうかに影響するだけで、Windows が \wsl$ や \wsl.localhost を通じて WSL のファイルシステムにアクセスする機能には影響しません。
automount.root
automount.root は Windows ドライブを WSL 内のどこにマウントするかを設定します。
デフォルトの場所は以下のとおりです。
root=/mnt
この場合、マウント結果は次のようになります。
C: -> /mnt/c
D: -> /mnt/d
もし以下のように変更すると、
root=/
マウント結果は次のようになる可能性があります。
C: -> /c
D: -> /d
通常はデフォルトの /mnt のままで問題ありません。
設定の適用
.wslconfig または /etc/wsl.conf を変更した後は、設定を反映させるために WSL を再起動する必要があります。
PowerShell で以下を実行します。
wsl --shutdown
その後、WSL を開き直します。
現在実行中のディストリビューションがあるかどうかは、以下のコマンドでも確認できます。
wsl --list --running
特定のディストリビューションだけを停止したい場合は、以下を使います。
wsl --terminate <ディストリビューション名>
例:
wsl --terminate Ubuntu
まとめ
簡単にまとめると、以下のようになります。
.wslconfigは Windows 側のグローバルな WSL 2 設定/etc/wsl.confは単一の WSL ディストリビューション内部の設定NATは WSL 2 のデフォルトネットワークモードmirroredは VPN、LAN アクセス、IPv6、マルチキャストといったシーンにより適している- Windows ドライブはデフォルトで
/mnt/c、/mnt/dなどのパスにマウントされる - WSL のファイルシステムは
\wsl$または\wsl.localhostで Windows からアクセス可能 - 設定を変更した後は、
wsl --shutdownを実行するか、WSL が完全に終了してから再起動する必要がある