【VS Code】Dev Containerでサブディレクトリをワークスペースとして開くとPythonカーネル(.venv)を見失う問題の解決策

はじめに

VS CodeのDev Container（Remote Container）を使ってPythonのデータ分析環境を構築している際、「ルートディレクトリ以外をワークスペースとして開くと、カーネルが認識されない」 という問題に直面した。

具体的には、Project Manager等の拡張機能を使って、リポジトリ内の特定のサブディレクトリ（テーマごとのフォルダなど）を直接開いて作業しようとすると、ルートにある .venv が見えなくなってしまう現象。いやー、まいったまいった。

この記事では、Dev Container環境特有の強みを生かして、この問題をシンプルに解決する方法を共有する。

前提環境

• 環境: VS Code Dev Container (Debianベース)
• 構成: ルートに .venv (仮想環境) があり、サブフォルダに個別の分析プロジェクトがある
• ツール: uv, Marimo, VS Code

ディレクトリ構造

以下のような構成になっている。.venv はプロジェクトの最上位にあるが、実際に作業したいのは analysis_category_B/project_beta などの下層ディレクトリだ。

/workspaces/my-data-science-project  <-- コンテナ内のルート
├── .venv                            <-- ここにPython環境がある
├── analysis_category_A
│   └── project_alpha                <-- ここをワークスペースとして開きたい
├── analysis_category_B
│   └── project_beta                 <-- ここをワークスペースとして開きたい
├── analysis_category_C
├── pyproject.toml
└── uv.lock

発生した問題

VS Codeの設定（devcontainer.json や settings.json）で、Pythonのパスを以下のように設定していた。

"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"

${workspaceFolder} は 「現在VS Codeで開いているフォルダのパス」 に展開される。

1. ルート（my-data-science-project）を開いている時
   • パスは /workspaces/my-data-science-project/.venv/... となり、正しく認識される。
2. サブディレクトリ（project_beta）を開いている時
   • パスは /workspaces/my-data-science-project/analysis_category_B/project_beta/.venv/... と解釈される。
   • そんな場所に .venv は無いため、カーネルが見つからないエラーになる。

解決策：コンテナ内の「絶対パス」で固定する

ローカル環境では人によってパスが違うため ${workspaceFolder} を使うのが定石だが、Dev Container環境では、ファイルパスは常に固定（例: /workspaces/プロジェクト名） だ。

あっ...そうか、コンテナ内なら固定パスでいいのか。

この特性を利用して、相対パス（変数）をやめ、「コンテナ内の絶対パス」 を直接指定することで解決する。

修正前の設定 (devcontainer.json / settings.json)

{
    // ${workspaceFolder} を使っているため、サブフォルダを開くとパスがズレる
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    
    "python.analysis.extraPaths": [
        "${workspaceFolder}/analysis_category_A",
        "${workspaceFolder}/analysis_category_B",
        "${workspaceFolder}/analysis_category_C"
    ]
}

修正後の設定 (devcontainer.json / settings.json)

以下のように、${workspaceFolder} を /workspaces/プロジェクト名 に書き換える。
また、JupyterやMarimoが確実にカーネルを見つけられるよう、jupyter.kernels.filter も追加するのがポイントだ。

{
    // 絶対パスで指定（どこを開いていても常にここを見に行く）
    "python.defaultInterpreterPath": "/workspaces/my-data-science-project/.venv/bin/python",
    
    // Jupyter/Marimo用にカーネルの場所を明示
    "jupyter.kernels.filter": [
        {
            "path": "/workspaces/my-data-science-project/.venv/bin/python",
            "label": "my-project-kernel" // わかりやすい名前
        }
    ],

    // 分析パス（Pylance用）も絶対パスに変更
    // これにより、サブフォルダを開いていても別フォルダのモジュールをimport補完できる
    "python.analysis.extraPaths": [
        "/workspaces/my-data-science-project/analysis_category_A",
        "/workspaces/my-data-science-project/analysis_category_B",
        "/workspaces/my-data-science-project/analysis_category_C"
    ],

    // その他の設定...
    "python.terminal.activateEnvironment": true,
    "marimo.disableUv": false,
    "marimo.disableUvIntegration": false,
    "jupyter.interactiveWindow.textEditor.language": "python"
}

※ /workspaces/my-data-science-project の部分は、自身のコンテナ内のパス（ターミナルで pwd コマンドを実行して確認可能）に合わせること。

結果

設定ファイルを保存して VS Code をリロード（Developer: Reload Window）した後、Project Managerでサブディレクトリ（project_betaなど）を直接開いてみた。

• 右上のカーネル選択に、ルートの .venv が表示されるようになった。あちちー！
• 別階層にある自作モジュールの import エラー（Pylance）が消えた。

これで、モノレポ構成でも快適にワークスペースを切り替えて開発できるようになった。Dev Containerを使う際は、あえて「絶対パス」を使うのがシンプルで強力な解決策になる。