はじめに (対象読者・この記事でわかること)

本記事は、Windows上でVSCodeを使用しつつ、WSL（Ubuntu）にインストールしたPython環境をリモートデバッグしたい開発者を対象としています。VSCodeのRemote‑WSL拡張の導入から、デバッグ構成の作成、実際にブレークポイントを設定してコードをステップ実行するまでのフローを具体的に示します。これにより、ローカルのWindows環境とWSL上のLinux環境をシームレスに行き来でき、Dockerや仮想マシンを別途用意する手間を省くことが可能です。初めてWSLでデバッグを行う方でも、手順通りに進めればすぐに動作確認ができるようになることを目指しています。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • Windows 10/11 の基本操作と VSCode のインストール経験
  • WSL（Ubuntu） のインストールと基本的な Linux コマンド操作（apt, pwd, ls など）
  • Python（3.8 以上） の基礎的な文法と pip によるパッケージ管理

Remote‑WSL と Python デバッグの概要

WSL は Windows 上で Linux カーネルをエミュレートし、Ubuntu などのディストリビューションを軽量に動かす仕組みです。VSCode の Remote‑WSL 拡張を利用すると、エディタ自体は Windows にありながら、実際のコード実行やターミナルは WSL 内で動作させることができます。この構成の最大の利点は、Linux 固有のライブラリや環境変数をそのまま利用できる点です。

Python のデバッグは、VSCode が提供する「Debug」機能を使うだけでなく、debugpy パッケージを介してリモートデバッグサーバーを立ち上げ、WSL 内のプロセスに接続する形でも実現できます。実際の開発フローは次のようになります。

  1. Windows に VSCode と Remote‑WSL 拡張をインストール
  2. WSL (Ubuntu) に Python と必要パッケージ（debugpy など）をインストール
  3. VSCode から WSL のフォルダーをリモートで開く
  4. .vscode/launch.json を作成し、type: "python" と request: "launch"（または attach）を設定
  5. デバッグ対象のスクリプトにブレークポイントを置き、デバッグを開始

これだけで、Windows の UI で Linux 環境のコードを直接デバッグでき、環境差異によるバグを早期に検出できます。

実践的な手順と実装方法

ステップ1：VSCode と Remote‑WSL 拡張のセットアップ

  1. VSCode をインストール
    - 公式サイトから Windows 用インストーラをダウンロードし、指示に従ってインストールします。
  2. Remote‑WSL 拡張をインストール
    - VSCode の拡張マーケットプレイスで「Remote - WSL」を検索し、Install をクリック。
  3. WSL のインストール（未導入の場合）
    - 管理者権限で PowerShell を開き、wsl --install -d Ubuntu を実行。再起動後、Ubuntu が起動します。

ポイント：インストール直後は Ubuntu がデフォルトで bash シェルを使用しますが、zsh 等に変更しても問題ありません。

ステップ2：WSL 側の Python 環境構築

  1. Python と pip のインストール
    bash sudo apt update sudo apt install -y python3 python3-pip python3-venv
  2. 仮想環境の作成（プロジェクトごとにおすすめ）
    bash mkdir -p ~/projects/debug-demo cd ~/projects/debug-demo python3 -m venv .venv source .venv/bin/activate
  3. debugpy のインストール
    bash pip install debugpy
  4. テストスクリプトの作成
    ```python # hello.py import time

def main(): for i in range(5): print(f"Count: {i}") time.sleep(1)

if name == "main": main() ```

ステップ3：VSCode で WSL プロジェクトを開く

  1. VSCode の左下にある緑色の >< アイコンをクリックし、Remote-WSL: New Window を選択。
  2. File > Open Folder で先ほど作成した ~/projects/debug-demo を指定。
  3. VSCode が自動でリモート環境に接続し、ターミナルも WSL 上で動作します。

ステップ4：デバッグ構成ファイル launch.json の作成

  1. デバッグビュー（サイドバーの虫眼鏡アイコン）を開き、create a launch.json file をクリック。
  2. 表示されるテンプレートから Python → Current File を選択すると、以下のような雛形が生成されます。 
Json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File (WSL)",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": false,
            "cwd": "${workspaceFolder}",
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        }
    ]
}
  1. 必要に応じて justMyCode を false に設定すると、標準ライブラリやサードパーティコードでもブレークポイントが有効になります。

ステップ5：ブレークポイントを設定しデバッグ開始

  1. hello.py の print(f"Count: {i}") 行にカーソルを合わせ、左側の余白をクリックして赤い点（ブレークポイント）を設定。
  2. デバッグビューで Python: Current File (WSL) を選択し、Start Debugging (F5) を押す。
  3. デバッグコンソールに Count: 0 が表示され、プログラムはブレークポイントで停止。変数ウィンドウで i の値やローカル変数を確認できる。

ハマった点やエラー解決

  • エラー 1：debugpy が見つからない`
  • 症状：ImportError: No module named 'debugpy' が発生。
  • 原因：VSCode が使用している Python 環境が、debugpy をインストールした仮想環境と異なる。

  • 解決策：VSCode の左下ステータスバーに表示される Python バージョンをクリックし、Select Interpreter で .venv/bin/python を選択。

  • エラー 2：デバッグが即座に終了する

  • 症状：F5 でデバッグ開始直後にプログラムが終了し、ブレークポイントが無視される。
  • 原因：launch.json の console が internalConsole になっている。

  • 解決策：console を "integratedTerminal" に変更し、ターミナル上で実行させる。

  • エラー 3：パスが Windows 形式になる

  • 症状：FileNotFoundError が発生し、WSL 側のパスが C:\Users\... と解釈される。
  • 原因：VSCode の cwd が Windows の作業ディレクトリになっている。
  • 解決策：launch.json の cwd を ${workspaceFolder} に統一し、WSL 側の絶対パスを使用する。

追加ヒント：Docker コンテナとの併用

WSL上でDocker Desktopを有効化すれば、同一環境でコンテナ化されたサービスとデバッグが可能です。docker-compose.yml を作成し、VSCode の Remote - Containers 拡張と組み合わせれば、さらに高度なマイクロサービス開発にも対応できます。

まとめ

本記事では、VSCode の Remote‑WSL 拡張を活用し、Windows 上から Ubuntu にインストールした Python 環境をシームレスにデバッグする手順を一から解説しました。

  • VSCode と Remote‑WSL の基本的なセットアップ方法
  • WSL 側での Python 仮想環境と debugpy のインストール
  • launch.json によるデバッグ構成の作成とブレークポイントの設定

これらを実践することで、Windows と Linux の垣根を超えた開発フローが実現し、環境依存バグの早期検出や開発効率の向上が期待できます。次回は、リモートデバッグを活かしたテスト自動化や、Docker コンテナとの統合手法について掘り下げる予定です。

参考資料