--- title: "WSLで開発環境を構築する手順｜.wslconfig調整とDocker連携・肥大化の対処" url: "https://www.issoh.co.jp/tech/details/17354/" published: 2026-09-05 updated: 2026-10-05 categories: ["インフラ・クラウド"] publisher: "株式会社一創" --- # WSLで開発環境を構築する手順｜.wslconfig調整とDocker連携・肥大化の対処 WSLを入れただけで止まっている開発環境は、たいてい3か所で詰まります。コードをWindows側のフォルダに置いたままで動作が遅い、メモリをホスト側に食われる、ext4.vhdxが数十GBに膨らんで戻らない。この記事では、`wsl --install` の実行から、コードの置き場所、`/etc/wsl.conf` と `.wslconfig` の書き分け、ネットワークモードの選択、Docker連携、ディスク肥大と読み取り専用エラーの復旧までをコマンドで示します。 ## まとめ｜WSLを開発機として使うための初期設定と運用の判断軸 結論から並べます。プロジェクトのファイルは必ずLinux側のホームディレクトリに置くこと。Windows側の `/mnt/c` に置いた状態はファイルIOが遅く、[公式のバージョン比較](https://learn.microsoft.com/ja-jp/windows/wsl/compare-versions)でもOSをまたぐファイルシステム性能はWSL2の弱点として明記されています。 設定ファイルは2つ用意します。ディストリビューション単位の設定は `/etc/wsl.conf`、仮想マシン全体の設定は `%UserProfile%\.wslconfig`。前者でsystemdと既定ユーザーを、後者でメモリとCPUの上限を決めます。`memory` の既定はWindows総メモリの50%、`processors` の既定は論理プロセッサと同数なので、開発機ではここを絞らないとホスト側が痩せます。 運用で効いてくるのは容量です。VHDは使うほど拡張されますが、ファイルを消しても自動では縮みません。実サイズを戻したいなら `[experimental]` の `sparseVhd` を先に有効化しておくこと。設定変更には8秒ルールがあるため、反映確認の前に `wsl --shutdown` を挟みます。[GitHubのリリース一覧](https://github.com/microsoft/WSL/releases)で確認できる安定版は2.7.13（2026年9月4日公開）です。 ## WSL 2.7.13時点のインストール手順とWSL1を選ぶ例外条件の判定 導入自体はコマンド1本で終わります。押さえるのは、何が同時に入るのか、どのディストリビューションを選ぶのか、そしてWSL2を使わない例外に自分が当てはまるのかの3点です。WSLの仕組みそのものやWSL1との構造的な違いは[WSL2とはの解説記事](https://www.issoh.co.jp/tech/details/3410/)で整理しているので、ここでは手を動かす部分に絞ります。 ### wsl –install で入るものと –web-download が要る場面 [公式のインストール手順](https://learn.microsoft.com/ja-jp/windows/wsl/install)によれば、管理者権限のPowerShellで `wsl --install` を実行すると、必要なコンポーネント一式と既定のUbuntuが入ります。企業ネットワークでMicrosoft Storeに到達できない環境なら `--web-download` を付けてオンラインソースから取得しますが、この場合は以後の更新も手動です。 ``` wsl --install wsl --list --online wsl --install Ubuntu-24.04 --no-launch wsl --set-default-version 2 wsl --version wsl -l -v ``` ディストリビューションを入れずWSLだけ先に用意するなら `--no-distribution`、展開先をCドライブから移すなら `--location` を使います。確認用が最後の2行。`wsl --version` が認識されない場合は受信トレイ版のまま更新されていないので、先に `wsl --update` を通します。 ### wsl –list –online の出力とUbuntu以外を選ぶ判断基準 選択肢はUbuntuだけではありません。`wsl --list --online` にはDebian、Kali、openSUSE、Oracle Linux、Fedoraが並びます。判断基準は好みではなく本番環境です。本番がRHEL系なら、手順書が二重になるのを避けるため開発側もRHEL系に寄せる。逆にマネージドサービス中心なら、情報量の多いUbuntuで揃えるほうが調べ物のコストは下がります。 [Ubuntuの導入と日本語化の解説](https://www.issoh.co.jp/tech/details/7492/)にある初期設定はWSL上でもほぼそのまま通用し、Fedoraは[WSL向けの公式対応](https://www.issoh.co.jp/tech/details/10014/)が入って以降は選びやすくなりました。 ### WSL1が速い3条件とwsl –set-version での切り替え時の注意 公式の比較表でWSL2がWSL1に負けている項目は「OSファイルシステム全体のパフォーマンス」ひとつだけです。該当するのは、プロジェクトファイルをWindows側に置き続ける必要がある場合、同じファイルをWindowsとLinuxの両方のツールでクロスコンパイルする場合、そしてシリアルポートにアクセスする場合の3つです。 切り替えは `wsl --set-version Ubuntu-24.04 1` の形式です。[公式のコマンドリファレンス](https://learn.microsoft.com/ja-jp/windows/wsl/basic-commands)はアーキテクチャ差により変換が失敗しうると警告しているため、大きなプロジェクトを抱えたディストリビューションでは先にエクスポートを取ってから実行してください。 ## Linuxファイルシステム側にコードを置く配置とVS Code接続の手順 WSLで最初に体感差が出るのがファイルの置き場所です。ここを間違えると、この後どれだけメモリを盛っても遅いままになります。あわせてエディタからの接続と、ディストリビューション側の初期設定も済ませます。 ### /mnt/c配下に置くと遅くなる理由とhomeへ移す実測手順 WSL2はVM内でLinuxカーネルを動かすため、Linux側ext4へのIOは速い一方、Windows側ドライブを見る `/mnt/c` は遅くなります。公式は、WSL2の初期バージョンでtarball展開がWSL1比で最大20倍、git cloneやnpm install、cmakeでおよそ2倍から5倍高速化したと記載しています。差が出るのはLinux側にファイルがある場合です。 すでにWindows側で作業してしまっているなら、移設は `cp -r` ではなくアーカイブ経由が確実。パーミッションとシンボリックリンクが崩れにくくなります。移設後は `node_modules` や `.venv` を作り直す前提で見積もってください。 ### VS CodeのWSL拡張で接続しリモートエクスプローラで開く流れ エディタはWindows側で動かし、コードだけLinux側に置くのが基本形です。[公式のVS Code連携手順](https://learn.microsoft.com/ja-jp/windows/wsl/tutorials/wsl-vscode)のとおりWSL拡張を入れ、ディストリビューションのシェルからプロジェクトディレクトリで `code .` を実行します。サーバー側コンポーネントがLinux側に展開され、以後の言語サーバーやフォーマッタもLinux側で動く構成です。 注意点は、拡張機能がWindows側とWSL側で別管理になること。ESLintやPythonの拡張はWSL側にも入れ直します。WSL内でPython本体の版を切り替えるなら[pyenvでPythonのバージョンを切り替える手順](https://www.issoh.co.jp/tech/details/17513/)が使えます。チーム全体で環境を固定する段階に来たら、WSLの上でさらに[開発コンテナを構成する方法](https://www.issoh.co.jp/tech/details/9565/)へ進むと、拡張機能とツールチェーンごとリポジトリで共有できます。 ### /etc/wsl.confでsystemdと既定ユーザーを固定する設定例 ディストリビューション単位の設定は `/etc/wsl.conf` です。[公式の詳細設定ドキュメント](https://learn.microsoft.com/ja-jp/windows/wsl/wsl-config)では automount、network、interop、user、boot などのセクションが定義されています。systemctl で管理するサービスを動かすなら、ここでsystemdを有効にします。 ``` [boot] systemd=true [user] default=devuser [interop] appendWindowsPath=false [automount] options="metadata,umask=22,fmask=11" ``` `appendWindowsPath=false` は好みが分かれる指定です。WindowsのPATHがLinux側の `$PATH` に流れ込まなくなるため、`node` や `python` がWindows側の実行ファイルに解決される事故は消えます。代わりに `code .` や `explorer.exe` も通らなくなるので、必要なものだけフルパスのエイリアスにしておきます。 ## .wslconfigでメモリとCPUを絞りWindows側の枯渇を防ぐ設定 WSL2はVMなので、割り当てを放置するとホストが痩せます。グローバル設定はユーザープロファイル直下の `.wslconfig`。既定では存在しないため自分で作成します。適用対象はWSL2で動くディストリビューション全体で、WSL1のものには効きません。 ### memory既定50%とprocessors既定値が招くメモリ不足の直し方 公式ドキュメントが示す既定値は、`memory` がWindows総メモリの50%、`processors` がホストの論理プロセッサと同数です。16GB搭載機なら8GBがWSL2の上限になり、そこにDockerのビルドが重なるとWindows側のブラウザや会議アプリが持っていかれます。開発機では明示的に上限を切ります。 ``` [wsl2] memory=8GB processors=4 swap=2GB localhostForwarding=true vmIdleTimeout=60000 [experimental] autoMemoryReclaim=gradual sparseVhd=true ``` サイズ値は単位を省くとバイト扱いになるため `8GB` のように必ず単位を付けること。`vmIdleTimeout` はアイドルからシャットダウンされるまでのミリ秒で、既定は60000です。 ### swapとautoMemoryReclaimでキャッシュ肥大を抑える指定 スワップの既定は「利用可能なRAMの25%をGB単位に切り上げた値」で、放っておくと `%Temp%\swap.vhdx` が数GB居座ります。考え方は[Linuxのスワップ領域の解説](https://www.issoh.co.jp/tech/details/3918/)と同じで、積むほど安全になるわけではありません。ビルドが通る最小限に切り、足りなければ増やす順序にします。 もうひとつの肥大要因がページキャッシュです。公式の比較ページには、WSL2はインスタンスがシャットダウンされるまでキャッシュ済みページをWindowsに返さないと明記されています。長時間セッションを張る開発機では `autoMemoryReclaim` を効かせます。値は `disabled`、`gradual`、`dropCache` の3種で、既定は `dropCache` です。 ### 8秒ルールとwsl –shutdown で設定を確実に反映させる手順 設定を書き換えたのに効かない、という詰まり方の大半はここです。公式は「構成変更の8秒ルール」として、シェルを全部閉じてからサブシステムが停止するまでおよそ8秒かかると説明しています。閉じてすぐ開き直すと、古い設定のまま動いているVMに再接続してしまうわけです。 確実なのは `wsl --shutdown` を明示的に打つこと。残存は `wsl --list --running` で確認できます。反映確認は、メモリなら `free -h`、CPUなら `nproc` の数字を見ます。 ## networkingMode=mirroredへ切り替える条件とNAT時の到達性 WSL2のネットワークは既定でNATです。ホストからコンテナへ、社内LANからWSLへ、といった到達性の要件が出た段階でミラーモードへの切り替えを検討します。設定は `.wslconfig` の `[wsl2]` セクションです。 ### NAT既定でlocalhostForwardingが効く範囲と再起動でIPが変わる件 NATモードでは `localhostForwarding`（既定 `true`）により、WSL側でlocalhostにバインドしたポートへWindows側から `localhost:3000` の形で到達できます。開発サーバーを見るだけならこれで十分。届かないのは逆方向で、WSL側からWindows上のサービスを叩くときは、デフォルトゲートウェイのアドレスを見に行く必要があります。 もうひとつの制約が、Hyper-V仮想マシンとして動く以上、再起動のたびにWSL側のIPが変わる点。IPを固定値として設定ファイルに書く運用は成立しません。 WSL側で立てたサーバーをインターネット側から一時的に見せたい場合は、ネットワークモードを変えるのではなくトンネルを張るほうが速い。エージェントを起動して公開URLを1本発行するまでの手順は[ngrokでローカルサーバーを外部公開する手順](https://www.issoh.co.jp/tech/details/17470/)に整理しました。 ### mirroredで開くignoredPortsとfirewall既定trueの関係 `networkingMode` に指定できる値は `none`、`nat`、`bridged`、`mirrored`、`virtioproxy` の5種です。ブリッジモードは2.4.5以降で非推奨とされたため、既存の手順書に `bridged` が残っているなら置き換え時期。`mirrored` にするとWindows側のインターフェースがLinux側にミラーされ、社内LANからの到達性を扱いやすくなります。 ``` [wsl2] networkingMode=mirrored firewall=true dnsTunneling=true [experimental] hostAddressLoopback=true ignoredPorts=53,3000 ``` `ignoredPorts` はミラーモード専用で、Windows側でそのポートが使われていてもLinuxアプリのバインドを許します。公式が挙げている例がDocker Desktopに53番を許すケースです。`firewall` は既定 `true` のままにしてください。切るとWSLのトラフィックがWindowsのファイアウォール規則から外れます。 ## Docker DesktopのWSL 2バックエンドと素のdocker導入の選択 WSLとコンテナの組み合わせは2通りです。Docker DesktopのWSL 2バックエンドを使うか、ディストリビューション内にDocker Engineを直接入れるか。ライセンス条件と起動速度で選び分けます。なお2026年9月29日のWSL 3.0.1からは、WSLに同梱されたwslc.exeでLinuxコンテナを直接動かす3つめの選択肢も加わりました。Compose未対応などの制約と使い分けは[WSL Containersとは？wslcの使い方とDocker Desktopとの使い分け](https://www.issoh.co.jp/tech/details/18105/)で整理しています。無料で使える境界の判定と、Desktopを外してDocker CEへ移す具体的な手順は[Docker Desktopの導入手順とライセンス境界をまとめた記事](https://www.issoh.co.jp/tech/details/17442/)に整理しました。[Dockerの導入と必要スペックの解説](https://www.issoh.co.jp/tech/details/6857/)の内容は、WSL上でもそのまま当てはまります。 ### Docker Desktop連携時に53番ポートで衝突したときの回避策 Docker Desktopは専用のWSLディストリビューションでエンジンを動かします。ミラーモードに切り替えたあとで詰まりやすいのがDNSで、Docker DesktopがLinux側の53番にバインドしようとしてWindows側の同じポートとぶつかります。 回避策は前述の `ignoredPorts` に53を含めること。公式ドキュメントがこの用途を例示しています。もうひとつ、VHDのマウント修復を行うときは `ERROR_SHARING_VIOLATION` を避けるためDocker Desktopを閉じる必要がある、と公式が注記しています。 ### wsl –export で環境を丸ごと持ち出しimportで復元する WSLの利点が出るのは端末を入れ替えるときです。`wsl --export` はディストリビューションのスナップショットをtarとして書き出し、`--vhd` を付ければ .vhdx 形式になります。復元は `wsl --import` で、展開先とバージョンを指定します。 ``` wsl --shutdown wsl --export Ubuntu-24.04 D:\wslbak\ubuntu.tar wsl --import Ubuntu-dev D:\wsl\ubuntu-dev D:\wslbak\ubuntu.tar --version 2 wsl -d Ubuntu-dev ``` インポートしたディストリビューションには実行可能ランチャーが無いため、`ubuntu config --default-user` の形式は使えません。既定ユーザーは `/etc/wsl.conf` の `[user]` セクションで指定します。 ## ext4.vhdxの肥大化と読み取り専用エラーを直す実作業手順 長く使ったWSLで必ず来るのが容量とマウントの問題です。どちらも公式に手順が用意されていますが、順番を間違えるとデータを失います。まず `wsl --shutdown` から始めてください。 ### 既定1TB割り当てとdfの見え方・wsl –manage –resize の条件 [公式のディスク領域ガイド](https://learn.microsoft.com/ja-jp/windows/wsl/disk-space)によれば、WSL2の各VHDには最初に1TBの最大ディスク領域が割り当てられます（リリース0.58.0より前は512GBまたは256GB）。実デバイスの空きが小さくても、`df` の出力にはこの割り当て最大値が出る仕様です。数字を見て慌てる必要はありません。 ``` wsl.exe --system -d Ubuntu-24.04 df -h /mnt/wslg/distro wsl --shutdown wsl --manage Ubuntu-24.04 --resize 2048GB ``` `wsl --manage --resize` が使えるのはWSL 2.5以降です。サイズ文字列はB、M、MB、G、GB、T、TBの形式で、`2.5TB` のような小数は現時点で受け付けません。古い環境では `diskpart` と `resize2fs` を組み合わせる手動手順です。 ### sparseVhdを有効にしてVHDの実サイズを戻す設定と副作用 VHDは使うほど拡張されますが、Linux側でファイルを消してもWindows上の .vhdx は縮みません。数十GB規模のイメージをビルドしては消す使い方だと、Cドライブだけが減っていきます。対処は `.wslconfig` の `[experimental]` にある `sparseVhd` で、既定は `false` のため明示的に `true` にします。 これは将来的な既定化を目指す試験的な設定と公式に位置づけられています。有効化しても既存のVHDには遡って効かないため、容量が既に膨らんだ環境では、エクスポートして作り直すほうが早い場面もあります。 ### マウント失敗時にe2fsckでext4を修復する4手順と注意点 突然の電源断のあとに「An error occurred mounting the distribution disk, it was mounted read-only as a fallback.」が出ることがあります。データ損失を避けるため読み取り専用にフォールバックした状態で、`touch` すら通りません。公式の復旧手順は4段階です。 ``` wsl.exe --shutdown wsl.exe --mount D:\wsl\ubuntu-dev\ext4.vhdx --vhd --bare wsl.exe lsblk wsl.exe sudo e2fsck -f /dev/sdc wsl.exe --unmount ``` `lsblk` で出たブロックデバイス名を `e2fsck` に渡します。ディストリビューションが1つしか無いと修復対象が使用中になり「ext file in use」で弾かれるため、作業用にもう1つ必要です。 ## WSLを採用しない場面と仮想マシン・クラウド環境への切替の判断 ここまで構築手順を並べましたが、WSLが合わない場面もはっきりしています。導入前に切り分けたほうが、後戻りの工数を払わずに済みます。 ### シリアルポート接続と厳しいメモリ制約でWSL2を外す判断ライン 公式が明示している除外条件は具体的です。WSL2はシリアルポートへのアクセスをサポートしません。組み込み開発でデバッグ用のシリアル接続が要るなら、この一点でWSL2は選べない。USBデバイスはUSBIPD-WINプロジェクト経由で使えるようになりましたが、追加のセットアップが前提になります。 メモリ制約が厳しい端末も外します。キャッシュ済みページはシャットダウンまで返らないため、8GB機で他のアプリと同居させると体感が落ちます。この条件に当たるなら、[ハイパーバイザーの型と使い分け](https://www.issoh.co.jp/tech/details/13370/)を踏まえ、リソースを明示的に切れるType2の仮想マシンへ寄せる判断が妥当です。Windows同梱のHyper-Vで仮想マシンを持つ場合の有効化と作成手順は[Hyper-Vの有効化と仮想マシン作成手順](https://www.issoh.co.jp/tech/details/17468/)にまとめました。 ### 受託開発でWSLを社内標準化するときの前提条件とDev Containerへの分岐 個人の開発機を速くする目的ならWSLで足ります。分岐点は、人数が増えて「私の環境では動く」が出始めたとき。WSLはWindowsの版、WSL本体の版、ディストリビューションの版、`.wslconfig` の内容という4層で差が出ます。設定ファイルをリポジトリに入れても、Windows 10の端末では `networkingMode` も `firewall` も効きません。この段階ではWSLを土台に置き、実際の開発環境はDev Containerへ移すほうが揃います。 複数案件を並行する受託の現場では、案件ごとにディストリビューションを分け `wsl --export` でアーカイブし、終了後に `wsl --unregister` で消す運用が効きます。後者はデータも設定も丸ごと消えるため、エクスポート済みであることを手順書の前提条件に書いてください。実行基盤とローカル環境をまとめて設計し直す段階なら、[インフラ構築の支援](https://www.issoh.co.jp/service/system/aws/)として本番構成の設計から開発環境の標準化までを引き受けています。 ## よくある質問 WSLの導入と運用でよく検索されている質問に、公式の記載を根拠に答えます。 ### WSLとWSL2は何が違いますか？ WSL1はシステムコールを変換するレイヤーで動き、WSL2は軽量ユーティリティVM内で実際のLinuxカーネルを動かします。公式の比較表では、完全なLinuxカーネル、システムコール互換性、systemd対応、マネージドVMの4項目がWSL2のみ対応。逆にOSをまたぐファイルシステム性能と、現行のVMwareやVirtualBoxとの併用はWSL1のみが優位とされています。 ### WSL2に必要なWindowsのバージョンは何ですか？ WSL2はWindows 11、またはWindows 10のバージョン1903（ビルド18362）以降で使えます。加えて `.wslconfig` でのグローバル設定はビルド19041以降、`networkingMode` や `firewall` はWindows 11の22H2以降が条件。バージョンは `winver` で確認します。 ### WSLのメモリ使用量を制限するにはどうしますか？ ユーザープロファイル直下に `.wslconfig` を作り、`[wsl2]` セクションへ `memory=8GB` のように書きます。既定はWindows総メモリの50%。単位を省くとバイト扱いになるためGBやMBを必ず付けてください。書き換えたあとは `wsl --shutdown` で一度落とします。閉じただけでは8秒ルールにより古い設定のまま再接続されることがあります。 ### WSLのディスク容量が減らないのはなぜですか？ VHDは使用量に応じて拡張される一方、Linux側でファイルを削除してもWindows上の ext4.vhdx は自動では縮まないためです。実サイズを戻す方向に効かせるには `.wslconfig` の `[experimental]` に `sparseVhd=true` を入れます。既定は `false` で、既存のVHDには遡りません。 ### WSLのバックアップと移行はどうやりますか？ `wsl --export` でディストリビューションをtarに書き出し、移行先で `wsl --import` に展開先パスを指定して取り込みます。`--vhd` を付ければ .vhdx 形式でのやり取りも可能。インポートしたディストリビューションは既定ユーザーの指定方法が変わり、`/etc/wsl.conf` の `[user]` セクションで設定します。 ## 関連記事 - [WSL2とは｜WSL1との違い・仕組み・インストール方法とメリット/デメリットを解説](https://www.issoh.co.jp/tech/details/3410/)：仕組みと概念の側を整理した記事です。 - [Ubuntuとは｜インストール手順・推奨スペック・日本語化と文字化け対策](https://www.issoh.co.jp/tech/details/7492/)：WSL上で動かすOSの初期設定に対応します。 - [Dockerとは｜仮想マシンとの違い・必要スペック・インストール手順](https://www.issoh.co.jp/tech/details/6857/)：WSL 2バックエンドで動かす前提の知識を補います。 - [VS Codeで開発コンテナを作る｜手順・devcontainer.json設定](https://www.issoh.co.jp/tech/details/9565/)：チームで環境を固定する段階の次の一手です。 - [Linuxコマンド一覧｜用途別早見表48選とUbuntu 26.04での変更点](https://www.issoh.co.jp/tech/details/2754/)：WSL上のシェル操作で使うコマンドをまとめています。 --- 出典: [WSLで開発環境を構築する手順｜.wslconfig調整とDocker連携・肥大化の対処]()（株式会社一創）