2026年7月29日

CursorをWSL2で使う完全ガイド:インストールからトラブル解決まで

CursorをWSLで使うための基本セットアップ

公式画面

CursorをWSLで使う基本セットアップ手順
  1. 01
    WindowsにCursorをインストール
    通常のWindows用インストーラ(.exe)でインストール。
  2. 02
    WSL拡張機能をインストール
    Cursorのマーケットプレイスから`ms-vscode-remote.remote-wsl`をインストール。バージョンダウングレード問題に注意。
  3. 03
    WSLターミナルでcursor .を実行
    プロジェクトディレクトリに移動し`cursor .`と入力。初回はポップアップでWSL接続を許可。
  4. 04
    トラブルシューティング
    無限ローディング時は`rm -rf ~/.cursor-server`でサーバー削除後再試行。リモートログでエラー確認。

WindowsへのCursorインストールとWSL拡張機能

室谷室谷代表取締役
まずはWindowsにCursorをインストールするところからですね。普通のWindows用インストーラ(.exe)で入れるだけで、特別なことは何もいらないです。
テキトー教師テキトー教師DotAI 認定講師
そうですね。その後、大事なのがWSL拡張機能を入れることです。

VS Codeと同じで、ms-vscode-remote.remote-wslっていう拡張機能をCursorのマーケットプレイスからインストールします。
室谷室谷代表取締役
でもここで注意点があって、Cursorが強制的に拡張機能のバージョンを0.81.8にダウングレードしちゃうことがあるんですよ。最新の0.88.5とかを手動で入れても、再起動すると戻される。
テキトー教師テキトー教師DotAI 認定講師
ああ、それよく聞きますね。最初から入ってるバージョンで動くならそのまま使うのが無難です。

どうしても最新が必要なら、フォーラムでも議論されてますが、まだ解決してない部分もあるみたいです。

WSLターミナルからcursor .でプロジェクトを開く

室谷室谷代表取締役
拡張機能が入ったら、あとはWSLのターミナルでプロジェクトディレクトリに移動してcursor .を叩くだけです。VS Codeのcode .と同じ感覚ですね。
テキトー教師テキトー教師DotAI 認定講師
でも初めてやるとき、cursorコマンドが見つからないってなりがちです。実はCursorをインストールするときにパスが通ってるはずなんですけど、WSL側から見えるようにする必要があります。
室谷室谷代表取締役
そうなんですよ。~/.bashrcとかでエイリアスを貼る方法もありますが、基本的には拡張機能がしっかり動いていれば、cursor .で勝手にWindows側のCursorが立ち上がってWSLのフォルダを開いてくれます。
テキトー教師テキトー教師DotAI 認定講師
ちなみに、cursor .じゃなくて初回は右下にポップアップが出て「WSLに接続しますか?」って聞かれることもあります。それで接続すればOKです。

初回接続時の注意点(WSL拡張のバージョン問題)

室谷室谷代表取締役
初回接続、うまくいけば一発なんですけど、たまに無限ローディングで止まることがあります。あれ、結構ハマる人いますよね。
テキトー教師テキトー教師DotAI 認定講師
そうですね。原因の一つが、さっき言った拡張機能のバージョンダウングレード問題です。

あとは、WSL側に~/.cursor-serverフォルダが壊れてることもあります。
室谷室谷代表取締役
対処法として、WSLのターミナルでrm -rf ~/.cursor-serverしてからもう一度cursor .すると、サーバーが再インストールされて直ることがあります。
テキトー教師テキトー教師DotAI 認定講師
それでもダメなら、Cursor側のリモートログ(Ctrl+Shift+P → Remote: Show Logs)を見ると、wsl exec: installServerScriptあたりでエラーが出てないか確認できます。そこから原因を特定するのが早いです。

WSL拡張機能のインストールと接続方法

WSL拡張機能のインストールと接続手順
  1. 01
    拡張機能のインストール
    マーケットプレイスから「Remote - WSL」を検索してインストール(ID: ms-vscode-remote.remote-wsl)
  2. 02
    WSLターミナルから接続
    WSLのターミナルで `cursor .` を実行。自動的にWSLに接続されプロジェクトが開く
  3. 03
    コマンドパレットから接続
    Windows側のCursorでCtrl+Shift+Pを押し、「WSL: Connect to WSL」を選択。新しいウィンドウがWSLリモートとして開く
  4. 04
    複数ディストリビューションの切り替え
    右下のリモートインジケーターをクリックするか、コマンドパレットから「WSL: Connect to WSL using Distro...」を選択してディストリを選ぶ

WSL拡張機能の入手とインストール手順

室谷室谷代表取締役
CursorのWSL拡張、VS CodeのRemote - WSLと全く同じものなんですよね。マーケットプレイスから "Remote - WSL" で検索するか、ms-vscode-remote.remote-wsl でインストール。
テキトー教師テキトー教師DotAI 認定講師
たしかに。初めての人は「WSL拡張ってどこから入れるんだろ」って迷うんですよ。

Cursorの拡張タブ開いて検索すれば一発です。
室谷室谷代表取締役
インストール後にWSLのターミナルから cursor . を叩けば、自動でWSLに接続されてプロジェクトが開く。これが一番簡単な始め方。
テキトー教師テキトー教師DotAI 認定講師
そうそう。拡張入れたら、あとはWSL側で普通に cursor . するだけ。

コードサーバーが自動でインストールされます。

コマンドパレットからWSLに接続

室谷室谷代表取締役
既にWindows側でCursorを開いてる状態からWSLプロジェクトを開きたい場合は、コマンドパレット(Ctrl+Shift+P)で "WSL: Connect to WSL" を選ぶ。
テキトー教師テキトー教師DotAI 認定講師
これ、拡張が入ってないと出てこないコマンドなので、先にインストールが前提ですね。接続すると新しいウィンドウがWSLリモートとして開きます。
室谷室谷代表取締役
ステータスバー左下に「WSL: Ubuntu」って表示が出れば成功。そこからフォルダを開くだけでOK。
テキトー教師テキトー教師DotAI 認定講師
ファイルエクスプローラーがWSLのファイルシステムを直接参照できるようになるので、Windows側のパスを意識しなくて済むんですよ。

複数WSLディストリビューションの切り替え

室谷室谷代表取締役
WSLに複数ディストリ(Ubuntu, Debian, Kaliなど)を入れている場合、右下のリモートインジケーターをクリックしてディストリを選択できる。
テキトー教師テキトー教師DotAI 認定講師
よくあるのが「デフォルト以外のディストリに繋げない」という相談。コマンドパレットから "WSL: Connect to WSL using Distro..." を選んで一覧から選べます。
室谷室谷代表取締役
一度接続しておけば、次回からそのディストリ用のウィンドウとして記憶される。MYUUUの現場でも、プロジェクトごとにディストリを分けて使ってる人いますね。
テキトー教師テキトー教師DotAI 認定講師
ただ、Agent Window周りはまだWSL対応が不完全なバージョンがあるので、安定を求めるならEditor Windowで使う方が無難です。

CursorのAI機能とWSLの連携

まとめ
CursorのAI機能とWSLの連携 - 課題と対処法
  • Tab・Chat: WSL経由でも正常に動作。Agentは拡張機能のバージョン問題(強制ダウングレード)によりコマンド実行が不安定。
  • Agent Window: WSLでは未サポートでポップアップループが発生。Editor Windowで使うか、`cursor --classic`で起動することで回避。
  • MCP設定: Agent WindowがWindows側のホームディレクトリを読むため、WSL側の設定が認識されない。Editor Windowで管理するか、Windows側に設定を複製する必要がある。

Tab・Chat機能をWSLで使う場合の制約

室谷室谷代表取締役
Tab補完やChat自体はWSL経由でも普通に動きます。ただ、Agentが絡むと話が変わってくるんですよね。
テキトー教師テキトー教師DotAI 認定講師
そうなんです。基本的なコード補完やChatでの質問は問題ないんですが、AgentがWSL内でコマンドを実行しようとすると、返ってくるのが「Debian (Default)」みたいな文字列だけ、というケースがあるみたいです。
室谷室谷代表取締役
結局、拡張機能のバージョンが古いのに引きずられてる感じですね。フォーラムでもWSL拡張が0.81.8に強制ダウングレードされるって報告が複数あって。
テキトー教師テキトー教師DotAI 認定講師
はい。ただTabやChatはその影響受けにくいので、そこだけ切り分けて使うという手もありますね。

AgentウィンドウとWSLの相性問題

室谷室谷代表取締役
Agent Windowに関しては、もう少し深刻です。Cursor 3系で「WSL拡張が必要」というポップアップがループして、結局使えないってバグレポートがいくつも出てます。
テキトー教師テキトー教師DotAI 認定講師
あれ、本当に厄介ですよ。Editor Windowでは普通にWSLが使えても、Agent Windowを開くとWSLのプロジェクトが認識されない。

公式でもWSLはAgent Windowでは未サポートという認識みたいです。
室谷室谷代表取締役
じゃあ今のところはEditor Windowで我慢するか、cursor --classicで起動するのが現実解ですね。
テキトー教師テキトー教師DotAI 認定講師
そうですね。あとAgent WindowがWSLじゃなくWindows側の設定を読む問題もあるので、そのあたりが修正されるまでは、ちょっと使い分けが必要です。

MCP設定をWSLで正しく読み込ませるには

室谷室谷代表取締役
MCPの設定も、WSL環境だとハマるポイントです。Agent WindowがWindowsユーザーのホームディレクトリにある.cursor/mcp.jsonを読んじゃうんですよ。
テキトー教師テキトー教師DotAI 認定講師
そうなんです。WSL側にMCP設定を置いても、Agent WindowからはWSLのファイルシステムにアクセスできず、「No file system provider found」というエラーになってしまいます。
室谷室谷代表取締役
今のところは、Editor WindowでWSLプロジェクトを開いた状態でMCP設定を管理するしかなさそうですね。もしくはWindows側にも同じ設定を複製するという手もあるけど、管理が二重になる。
テキトー教師テキトー教師DotAI 認定講師
はい。WSLの.cursorフォルダにシンボリックリンクを貼っても上手くいかないという報告もあるので、当面はEditor Windowメインで運用するのが無難だと思います。

よくあるトラブルとその解決策

まとめ
よくあるトラブルとその解決策
  • WSL拡張の自動ダウングレード: Cursorが強制的に古いバージョンに戻す。暫定的にそのまま使うか、フォーラムで情報収集。
  • WSL接続が無限ループ: ~/.cursor-serverフォルダ削除→再起動で9割復旧。WSL再起動やダウングレード→アップデートも有効。
  • Git重複検出・ファイル監視エラー: git.autoRepositoryDetectionをfalseに。inotify上限を拡大(524288)。.gitignoreで監視対象除外。

WSL拡張が自動ダウングレードされる問題

室谷室谷代表取締役
CursorがWSL拡張を勝手にバージョン0.81.8に戻す問題、フォーラムでも頻出ですよね。最新の0.88.5を入れても再起動で強制ダウングレードされる。
テキトー教師テキトー教師DotAI 認定講師
そうなんです。VSCodeでは問題ないのにCursorだけ古いバージョンに固定される。

実際に使うとAgentがWSLのコマンドを正しく実行できなくなったりします。
室谷室谷代表取締役
これ、中の人の話だと互換性の問題らしいですけど、ユーザー視点だと不便ですよね。一時的な回避策としては、とりあえずそのまま使うか、ダウングレードされた状態で動くことを確認するしかない。
テキトー教師テキトー教師DotAI 認定講師
ただ、AgentがWSLと連携できないと意味がないので、最新のアップデートを待つか、フォーラムで進捗を追うのが現実的ですね。

WSL接続が無限ループする・開けない

室谷室谷代表取締役
次に「Open Folderが無限ロード」「リモート拡張ホストが起動しない」というケース。Cursor 3.xで報告が多い。
テキトー教師テキトー教師DotAI 認定講師
最初にやるべきは、WSL内の~/.cursor-serverフォルダを削除して再起動することです。サーバー側のキャッシュが壊れていると無限ループになります。
室谷室谷代表取締役
それでも直らない場合、WSLの再起動やWindowsの再起動も試す価値あり。MYUUUの現場でも、この手順で9割は復旧してます。
テキトー教師テキトー教師DotAI 認定講師
あと、古いバージョンのCursor(2.x)で動いていたなら、一度ダウングレードしてから再度アップデートする方法もあります。

Gitの重複検出やファイル監視エラー

室谷室谷代表取締役
Git周りだと、ファイルが全部変更扱いされる問題が地味に痛い。git.autoRepositoryDetectionが原因で、Source Controlが二重表示になることも。
テキトー教師テキトー教師DotAI 認定講師
解決策は設定で"git.autoRepositoryDetection"をfalseにすること。あと、inotifyの監視上限に引っかかると「ファイル変更を監視できません」という警告が出ます。
室谷室谷代表取締役
その場合はWSL内でfs.inotify.max_user_watchesを増やす。標準だと8192なので、524288くらいに増やすと大型プロジェクトでも安心。
テキトー教師テキトー教師DotAI 認定講師
ついでに、大きなnode_modulesやgeneratedディレクトリは.gitignoreに追加して監視対象から外すと、さらに安定します。

VS CodeからCursorに移行する際のWSL設定の注意点

まとめ
VS CodeからCursor移行時のWSL設定注意点
  • codeコマンドは `alias code='cursor'` で置き換え。両方使う場合は環境変数で切替。
  • ターミナルのデフォルトシェルをWSLのbashに変更、またはRemoteウィンドウで開く。
  • WSL拡張機能の互換性に注意。最新版が使えない場合があるので互換性リスト確認、Remote内で再インストール。

codeコマンドの置き換えとカスタマイズ

室谷室谷代表取締役
VS Code で code . してたのを Cursor でも同じようにやりたいって話、よく聞きますね。
テキトー教師テキトー教師DotAI 認定講師
そうなんです。WSL のターミナルから cursor . で開けるんですが、最初は知らないですよね。
室谷室谷代表取締役
うちの現場では alias code='cursor' を .bashrc に仕込んでます。移行のストレスが減るのでおすすめです。
テキトー教師テキトー教師DotAI 認定講師
ただし、VS Code と Cursor を両方使う人は競合するので注意が必要です。環境変数で切り替えると良いですよ。

ターミナル設定とPATHの引き継ぎ

室谷室谷代表取締役
ターミナルのデフォルトシェルが PowerShell になってて、WSL の Git と競合するケースがあります。
テキトー教師テキトー教師DotAI 認定講師
それ、よくあるトラブルですね。ファイルのパーミッションが変わって「全部 modified」って表示されるやつ。
室谷室谷代表取締役
Cursor の設定で terminal.integrated.defaultProfile.windows を WSL の bash に変えれば解決します。
テキトー教師テキトー教師DotAI 認定講師
あと、WSL 拡張機能を入れて Remote ウィンドウで開くのも確実です。PATH も WSL 側のがそのまま使えます。

拡張機能の互換性

室谷室谷代表取締役
VS Code の拡張機能がそのまま使えると思いきや、WSL 関連で引っかかるポイントがあります。
テキトー教師テキトー教師DotAI 認定講師
例えば Cursor が強制的に WSL 拡張機能のバージョンを古いのに戻しちゃうとか。
室谷室谷代表取締役
コミュニティでも報告が上がってますね。最新版が使えない場合があるので、Cursor 側の互換性リストを確認したほうがいいです。
テキトー教師テキトー教師DotAI 認定講師
それでも基本は動きます。Python 拡張なんかは別途インストールが必要なケースもあるので、Remote ウィンドウ内で入れ直すのが確実です。

WSL環境でCursorを最大限活用するコツ

WSL環境でCursorを最大限活用するコツ
パフォーマンス改善(inotify制限の増加)
fs.inotify.max_user_watches を524288に設定する。ファイル監視の警告が消えエクスプローラの応答が改善。
安定版リリースの選択と更新管理
業務ではStableトラックを選択。自動更新を切るにはSettingsでUpdate: Modeをnoneに設定する。WSL関連フォーラムで安定バージョンを確認。
チーム開発でのベストプラクティス
git.autoRepositoryDetectionをfalseに。files.watcherExcludeでnode_modules等を除外。WSLのデフォルトシェルをWSL側のbashに設定。

パフォーマンス改善(inotify制限の増加)

室谷室谷代表取締役
WSLで大規模リポジトリを開くと、ファイル監視が間に合わなくてフリーズすることがあるんですよね。これ、結構クリティカル。
テキトー教師テキトー教師DotAI 認定講師
たしかに。最初に戸惑うのが「Unable to watch for file changes」の警告です。

プロジェクトが大きいとデフォルトの監視制限にすぐ引っかかる。
室谷室谷代表取締役
解決策はシンプルで、WSLの中でinotifyの上限を引き上げるだけ。fs.inotify.max_user_watches を524288に設定すれば、ほとんどのケースで安定します。
テキトー教師テキトー教師DotAI 認定講師
実践すると、あの警告が消えてエクスプローラの応答も改善されます。ただしCursor本体のバグでフリーズするケースもあるので、それと混同しないように。

安定版リリースの選択と更新管理

室谷室谷代表取締役
よくあるのが、Nightly版でWSL周りが突然動かなくなるパターン。3.5.8のNightlyで不具合が出たという報告もありますね。
テキトー教師テキトー教師DotAI 認定講師
業務で使うならStableトラックにしておくのが無難です。Cursorのリリースは速いので、WSL周りの修正が入るタイミングを見極めたい。
室谷室谷代表取締役
自動更新を切る方法もあります。SettingsでUpdate: Modeをnoneに設定すれば、バージョンを固定できる。

チームで揃えたい場合も便利です。
テキトー教師テキトー教師DotAI 認定講師
重要なのは、安定したバージョンを知っておくこと。WSL関連のフォーラムをチェックして、問題が出ていないバージョンを選ぶのがコツです。

チーム開発でのベストプラクティス

室谷室谷代表取締役
チームでWSL上にリポジトリを置く場合、git周りの設定が結構重要。git.autoRepositoryDetectionが原因で二重検出されて重くなる事例がありました。
テキトー教師テキトー教師DotAI 認定講師
あれはハマる人多いですね。設定でfalseにしておけば、Source Controlが安定します。
室谷室谷代表取締役
あと、node_modulesのような巨大なディレクトリはファイル監視から外す。files.watcherExclude にパターンを追加しておけば、inotifyの消費を抑えられます。
テキトー教師テキトー教師DotAI 認定講師
現場でよく聞くのは、WSLのデフォルトシェルをWSL側のbashにしておくと、Cursorのターミナルが正しく動作するという話。ターミナルがWindows側を向いてると、パスが混ざって混乱するんですよね。

よくある質問

Q1. CursorはWSL1でも使えますか?

室谷室谷代表取締役
正直WSL1だとファイルシステムのI/Oが遅くて、AIの補完がカクつくんですよね。WSL2前提で設計されてる部分があるので、推奨はしません。
テキトー教師テキトー教師DotAI 認定講師
現場でよく聞かれますが、WSL1だとNode.jsのパッケージインストールでもタイムアウトしやすくなる。WSL2に移行した方がストレスなく使えますよ。

Q2. WindowsとWSLのファイルをまたいでAI機能は使えますか?

室谷室谷代表取締役
使えますが、注意点があります。CursorのAIは開いているファイルのパスを認識するので、Windows側のファイル(/mnt/c/配下)を直接編集すると応答が遅くなるケースがある。
テキトー教師テキトー教師DotAI 認定講師
実はそうなんですよ。WSLのファイルシステム内にプロジェクトを置くのが無難です。

Windows側からシンボリックリンクで参照する方法もありますが、最初はWSL内で完結させるのがおすすめ。

Q3. CursorのGPUアクセラレーションはWSLで効きますか?

室谷室谷代表取締役
NVIDIA GPUを使っていて、CUDA on WSLが有効なら使えます。ただ、TensorFlowとかPyTorchのバージョン依存があるので、公式の互換性リストを見た方がいいですね。
テキトー教師テキトー教師DotAI 認定講師
現場でハマるのがドライバのバージョン。Windows側のGeForce Game ReadyドライバがWSLのCUDAと合わないことがあります。

Studioドライバに切り替えると安定することが多いです。

Q4. 複数のWSLディストリビューション(UbuntuやDebian)を切り替えて使えますか?

室谷室谷代表取締役
できます。CursorのRemote Explorerで各ディストリを認識するので、プロジェクトごとに使い分けられます。

ただし、拡張機能の設定はディストリごとに独立してるので注意。
テキトー教師テキトー教師DotAI 認定講師
そこがポイントですね。例えばPythonのインタプリタパスが違うと、AIのコード補完が変な提案をすることがあります。

開く前にWSLのターミナルで確認するクセをつけると良いです。

Q5. VS CodeのWSL設定をそのままCursorにインポートできますか?

室谷室谷代表取締役
基本的には手動で再設定が必要です。CursorはVS Codeからフォークされてますが、拡張機能のIDが微妙に違うことがある。

Settings Sync系の拡張機能を使っても、WSL内の設定までは同期されない場合が多いですね。
テキトー教師テキトー教師DotAI 認定講師
なので、移行時は一度WSL内でcursor .を実行して、必要な拡張機能だけインストールし直すのが確実です。特にRemote WSL拡張機能は忘れずに。

まとめ

室谷室谷代表取締役
WSL2とCursorの組み合わせ、正直今の最強の開発環境の一つだと思ってます。特にAI補完がLinuxネイティブで動くのが大きい。
テキトー教師テキトー教師DotAI 認定講師
そうですね。最初のセットアップさえ一通り終われば、Windowsでも快適にLinux開発ができる。

初心者でも手順通りやれば詰まるところは少ないと思います。
室谷室谷代表取締役
あとは「VS Codeから移行するときの注意点」で話した通り、設定の引き継ぎは手間がかかるけど、慣れれば生産性は上がる。MYUUUの現場でもエンジニアの8割がCursor + WSL2に移行してます。
テキトー教師テキトー教師DotAI 認定講師
まずはWSL2のインストールから、一歩ずつ試してみてください。CursorのRemote Explorerで接続できたら、もう9割完成ですから。
室谷室谷代表取締役
そう、あとは実際にコードを書いて、AIに質問してみる。そこでつまずいたら今回のトラブルシューティングを参照してもらえれば。

Related

関連記事

New Articles

新着記事

ガイド

Grokの読み方は「グロック」か「グロク」か?公式回答と会社名・料金の最新事情

2026年11月18日
室谷テキトー教師
ガイド

GoogleのAIモードとAIによる概要の消し方|公式オフ機能の有無とPC・スマホの回避策

2026年11月18日
室谷テキトー教師
ガイド

Azure OpenAI Serviceとは?料金・モデル一覧・データの扱いを最新情報で整理

2026年11月18日
室谷テキトー教師
ニュース

Perplexityの「Orchestrator API」とは?45以上のモデルを1つのAPIキーに統合

2026年11月18日
室谷テキトー教師
ニュース

Microsoftの「Copilot Workspaces」とは?人とエージェントが協働する新体験

2026年11月18日
室谷テキトー教師
ガイド

Geminiのファミリープランは何人まで?Google AI Proを家族で割る料金と設定の手順

2026年11月18日
室谷テキトー教師
ニュース

Microsoft MAIとは?Ignite 2026で発表の7モデルと料金

2026年11月18日
室谷テキトー教師
ニュース

Replit Missionsとは?エージェントスウォームで目標達成型の自律実行

2026年11月18日
室谷テキトー教師
ニュース

Copilot Fusion Maxとは?Terminal-Bench 4.1首位の自動モデル選択

2026年11月18日
室谷テキトー教師
ニュース

Googleの「Gemini Tasks」とは?日本でも無料開始、Gemini 4 Hydrogen搭載

2026年11月18日
室谷テキトー教師

Join

AIプレナーになる。

入会は審査制です。いまの事業と、AIで何を動かしたいのかを聞かせてください。

参加を申請する