VSCodeからDockerコンテナへ接続する方法

2026年10月26日

VSCodeからDockerコンテナへ接続すると、コンテナ内に構築したLinux環境やNode.js、Python、PHP、C++などの開発環境を、VSCode上から利用できます。

代表的な方法は、Microsoftが提供している「Dev Containers」拡張機能を使用する方法です。

Dev Containersを利用すると、コンテナ内のファイル編集だけでなく、ターミナル操作、IntelliSense、デバッグ、VSCode拡張機能、ポート転送などを利用できます。

単にコンテナ内部のシェルへ入るだけではなく、DockerコンテナをVSCodeの開発環境として利用できる点が特徴です。

VSCodeからDockerコンテナへ接続する仕組み

Dev Containersを使用する場合、VSCodeの画面そのものは基本的にホストOS上で動作します。

一方、コンテナ内にはVS Code Serverが配置され、VSCodeからDocker経由で接続します。

イメージとしては、次のような構成です。

ホストOS
│
├─ VSCode
│
└─ Docker
     │
     ▼
Dockerコンテナ
├─ VS Code Server
├─ Node.js
├─ Python
├─ PHP
├─ GCC
├─ Git
└─ その他の開発ツール

そのため、VSCodeの操作画面はローカルPC上にありながら、ターミナルやデバッグ、言語サーバーなどはコンテナ側の環境を利用できます。

VSCodeからDockerへ接続するために必要なもの

Dockerコンテナへ接続するには、基本的に次の環境を用意します。

Docker
VSCode
Dev Containers拡張機能

WindowsやmacOSではDocker Desktopを利用する方法が一般的です。

LinuxではDocker Engineを利用できます。

Dockerが利用できるか確認する

まず、ターミナルやPowerShellからDockerが利用できるか確認します。

docker --version

Dockerが正しくインストールされていれば、バージョン情報が表示されます。

続いて、次のコマンドを実行します。

docker ps

Dockerデーモンへ接続できれば、現在実行中のコンテナ一覧が表示されます。

Docker Desktopを利用している場合は、Docker Desktop自体が起動していることも確認してください。

Dev Containers拡張機能をインストールする

VSCodeを起動し、拡張機能画面を開きます。

WindowsやLinuxでは、次のショートカットを使用できます。

Ctrl + Shift + X

macOSでは、VSCodeの拡張機能画面から同様に検索できます。

検索欄に次のように入力します。

Dev Containers

Microsoftが提供している「Dev Containers」をインストールします。

起動済みDockerコンテナへ接続する方法

すでに起動しているDockerコンテナへ接続する場合は、「Attach to Running Container」を利用します。

Dockerコンテナを確認する

まず、現在起動しているコンテナを確認します。

docker ps

例えば、次のようなコンテナが起動しているとします。

CONTAINER ID IMAGE STATUS NAMES
abc123def456 ubuntu:24.04 Up 5 minutes my-container

この場合、my-containerへVSCodeから接続できます。

コマンドパレットから接続する

VSCodeでコマンドパレットを開きます。

WindowsやLinuxでは、次のショートカットです。

Ctrl + Shift + P

macOSでは次のショートカットです。

Command + Shift + P

コマンドパレットに次のように入力します。

Dev Containers: Attach to Running Container...

表示されたコンテナ一覧から、接続したいコンテナを選択します。

すると、新しいVSCodeウィンドウが開き、対象コンテナへ接続されます。

Remote ExplorerからDockerコンテナへ接続する方法

コマンドパレットだけでなく、Remote ExplorerからもDockerコンテナへ接続できます。

VSCodeのActivity BarからRemote Explorerを開きます。

コンテナ一覧を表示し、対象のコンテナから「Attach to Container」を選択します。

頻繁に複数のコンテナを扱う場合は、Remote Explorerから操作するほうが分かりやすいこともあります。

Dockerコンテナ内のフォルダを開く

コンテナへ接続した直後は、作業対象のフォルダが開かれていない場合があります。

その場合は、VSCodeの「File」から「Open Folder」を選択します。

例えば、アプリケーションが次のディレクトリにある場合は、そこを開きます。

/app

または、開発環境によっては次のようなパスを使用します。

/workspace

Docker Composeで次のように設定している場合を考えてみます。

services:
  app:
    volumes:
      - .:/workspace

この場合、ホスト側のプロジェクトディレクトリが、コンテナ内の/workspaceへマウントされます。

VSCodeから/workspaceを開けば、ホスト側のソースコードをコンテナ環境で編集できます。

Dockerコンテナへ接続できる簡単な例

Ubuntuコンテナを作成して、VSCodeから接続してみます。

次のコマンドを実行します。

docker run -dit --name vscode-test ubuntu:24.04 bash

主なオプションの意味は次のとおりです。

-d
バックグラウンドで実行

-i
標準入力を維持

-t
仮想端末を割り当て

--name
コンテナ名を指定

起動状態を確認します。

docker ps

vscode-testが表示されたら、VSCodeから次の順番で操作します。

Ctrl + Shift + P
↓
Dev Containers: Attach to Running Container...
↓
vscode-test

これでUbuntuコンテナへ接続できます。

VSCodeからDockerコンテナ内のターミナルを利用する

Dockerコンテナへ接続した状態でVSCodeの統合ターミナルを開くと、コンテナ内でコマンドを実行できます。

WindowsやLinuxでは、次のショートカットでターミナルを開けます。

Ctrl + `

例えば、次のコマンドを実行します。

pwd

コンテナ内の現在位置が表示されます。

また、次のようなコマンドも実行できます。

ls

cat /etc/os-release

Ubuntuコンテナであれば、Ubuntuに関する情報が表示されます。

docker execとの違い

Dockerでは、次のコマンドでもコンテナ内部へ入れます。

docker exec -it コンテナ名 bash

ターミナル操作だけを見ると、Dev Containersによる接続と似ています。

ただし、Dev Containersではターミナル以外にも、ファイル編集、IntelliSense、デバッグ、VSCode拡張機能、ポート転送などを利用できます。

そのため、単にコンテナ内部のシェルを操作するだけならdocker exec、本格的にVSCodeから開発するならDev Containersと考えると分かりやすいです。

devcontainer.jsonを使って開発環境を構築する

本格的にDockerを開発環境として利用する場合は、devcontainer.jsonを使用する方法があります。

プロジェクト内に次のようなディレクトリを作成します。

project
├─ .devcontainer
│ └─ devcontainer.json
├─ src
└─ package.json

devcontainer.jsonには、VSCodeから利用する開発コンテナの設定を記述できます。

例えば、次のような内容です。

{
  "name": "Node Development",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm",
  "forwardPorts": [3000],
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint"
      ]
    }
  }
}

devcontainer.jsonで設定できる主な内容

devcontainer.jsonでは、次のような内容を指定できます。

使用するDockerイメージ
使用するDockerfile
VSCodeが接続するサービス
ワークスペースのパス
ポート転送
VSCode拡張機能
接続ユーザー
環境変数
コンテナ作成後に実行するコマンド

開発環境の設定をファイルとして管理できるため、チーム開発との相性がよい方法です。

devcontainer.jsonからコンテナを開く方法

devcontainer.jsonを作成したら、VSCodeでプロジェクトを開きます。

その後、コマンドパレットから次のコマンドを実行します。

Dev Containers: Reopen in Container

VSCodeが設定内容を読み取り、必要に応じてDockerイメージを取得したり、コンテナをビルドしたりします。

処理が完了すると、プロジェクトがコンテナ環境で開かれます。

DockerfileをDev Containersで利用する

独自の開発環境を構築したい場合は、Dockerfileを利用できます。

例えば、次のような構成にします。

project
├─ .devcontainer
│ ├─ devcontainer.json
│ └─ Dockerfile
└─ src

Dockerfileの例は次のとおりです。

FROM node:22-bookworm

WORKDIR /workspace

RUN apt-get update \
    && apt-get install -y git curl \
    && rm -rf /var/lib/apt/lists/*

devcontainer.jsonでは、次のようにDockerfileを指定します。

{
  "name": "My Development Container",
  "build": {
    "dockerfile": "Dockerfile"
  }
}

これにより、Dockerfileで作成したイメージをDev Containersの開発環境として利用できます。

DockerfileとpostCreateCommandの違い

開発環境の初期化では、DockerfileとpostCreateCommandのどちらを使うべきか迷うことがあります。

Dockerfileに向いている処理

Dockerfileには、イメージそのものへ含めたい処理を記述します。

例えば、次のような内容です。

OSパッケージのインストール
Gitのインストール
Node.jsやPythonの導入
ビルドツールの導入

postCreateCommandに向いている処理

postCreateCommandは、開発コンテナが作成された後に実行したい処理に向いています。

例えば、次のように設定できます。

{
  "postCreateCommand": "npm install"
}

プロジェクトファイルを使用する依存関係のインストールなどでは、postCreateCommandのほうが適している場合があります。

Docker ComposeとDev Containersを組み合わせる

Web開発では、複数のコンテナをDocker Composeで管理することもあります。

例えば、次のような構成です。

Webアプリ
PostgreSQL
Redis
Nginx

Docker Composeの例は次のとおりです。

services:
  app:
    build: .
    volumes:
      - .:/workspace

  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: password

Dev Containersでは、どのComposeサービスへVSCodeを接続するのかを指定できます。

{
  "name": "Docker Compose Development",
  "dockerComposeFile": "../compose.yaml",
  "service": "app",
  "workspaceFolder": "/workspace"
}

この場合、appサービスへVSCodeが接続します。

イメージすると次のようになります。

Docker Compose

├─ app
│ └─ VSCodeが接続
│
└─ db

Docker Composeは事前に起動する必要があるのか

Attach to Running Containerを使用する場合は、対象コンテナが起動済みである必要があります。

一方、devcontainer.jsonからDocker Composeを利用する場合は、必ずしも事前にdocker compose upを実行する必要はありません。

Dev Containers側から必要なサービスを起動して開発環境を構築できます。

そのため、次のように整理できます。

Attach to Running Container
→ 起動済みコンテナへ接続

Reopen in Container
→ Dev Containers側から開発環境を作成・起動可能

forwardPortsとDocker Composeのportsの違い

Dev Containersでは、次のようにforwardPortsを指定できます。

{
  "forwardPorts": [3000]
}

これは、コンテナ内の3000番ポートをVSCode経由でローカル側へ転送する設定です。

一方、Docker Composeでは次のように記述できます。

ports:
  - "3000:3000"

これはDocker自身がコンテナのポートをホストへ公開する設定です。

両者は似ていますが、仕組みは異なります。

forwardPorts

Dev Containersによるポート転送です。

Dockerコンテナ
3000番ポート
↓
VSCode
↓
ローカルPC

ports

Dockerによるポート公開です。

Dockerコンテナ
3000番ポート
↓
Docker
↓
ホストPCの3000番ポート

必ずしも両方を設定する必要はありません。

Dev Containers中心で開発する場合はforwardPortsだけで十分なケースもあります。

ブラウザからコンテナ内のWebアプリへアクセスする

例えば、コンテナ内で次のコマンドを実行したとします。

npm run dev

アプリケーションが3000番ポートで起動している場合、forwardPortsで次のように指定できます。

{
  "forwardPorts": [3000]
}

通常は、ブラウザから次のようなURLへアクセスできます。

http://localhost:3000

ただし、ローカル側ですでに3000番ポートが使用されている場合などは、別のポート番号へ転送されることがあります。

実際の転送先ポートは、VSCodeの「PORTS」ビューで確認できます。

workspaceFolderを設定する

コンテナ接続時に、VSCodeで最初に開くディレクトリを指定できます。

例えば、次のように記述します。

{
  "workspaceFolder": "/workspace"
}

Docker Compose側で次のように設定している場合、相性のよい構成になります。

volumes:
  - .:/workspace

この場合、ホスト側のプロジェクトディレクトリと、コンテナ内の/workspaceが対応します。

コンテナ内で使用するユーザーを指定する

Dev Containersでは、remoteUserを指定できます。

例えば、次のように記述します。

{
  "remoteUser": "vscode"
}

remoteUserは主に、VSCodeやターミナル、タスク、デバッグなどがコンテナ内でどのユーザーとして動作するかを指定する設定です。

Dockerコンテナ自体の実行ユーザーを変更する設定とは必ずしも同じではありません。

ファイル所有者や権限問題を避けるために、開発環境では非rootユーザーを利用する設計が適している場合があります。

remoteEnvで環境変数を設定する

Dev Containersでは、VSCode側のプロセスに環境変数を設定できます。

例えば、次のように記述します。

{
  "remoteEnv": {
    "NODE_ENV": "development"
  }
}

remoteEnvは、主にVSCodeやVSCodeから起動されるプロセスへ適用される環境変数です。

Dockerコンテナ全体に設定される環境変数とは役割が異なります。

postAttachCommandを利用する

コンテナへ接続した後にコマンドを実行したい場合は、postAttachCommandを利用できます。

{
  "postAttachCommand": "echo connected"
}

VSCodeがコンテナへ接続するたびに実行したい処理に向いています。

ただし、依存関係のインストールのように毎回実行する必要がない処理では、postCreateCommandのほうが適している場合があります。

AttachとReopen in Containerの違い

「Attach to Running Container」と「Reopen in Container」は用途が異なります。

Attach to Running Container

Attach to Running Containerは、すでに起動しているDockerコンテナへVSCodeを接続する方法です。

docker run
↓
コンテナ起動
↓
VSCodeからAttach

一時的にコンテナ内を調査したい場合や、すでに動いている環境を利用したい場合に向いています。

なお、Attachの場合でも、Attached Container Configurationを利用して、ワークスペースやポート、ユーザーなどの設定を保存できます。

Reopen in Container

Reopen in Containerは、プロジェクト内のdevcontainer.jsonを使用して開発環境を構築する方法です。

プロジェクト
│
├─ ソースコード
│
└─ .devcontainer
    └─ devcontainer.json
          ↓
開発コンテナ作成
          ↓
VSCodeから接続

チーム開発や、再現可能な開発環境を構築したい場合に向いています。

VSCodeからDockerコンテナへ接続できない場合の対処法

Dockerコンテナへ接続できない場合は、順番に原因を確認します。

Dockerが起動しているか確認する

次のコマンドを実行します。

docker ps

Dockerデーモンへ接続できない場合は、Docker DesktopやDocker Engineの起動状態を確認します。

コンテナが起動しているか確認する

実行中コンテナを確認します。

docker ps

停止中コンテナも含めて確認する場合は、次のコマンドを使用します。

docker ps -a

停止しているコンテナは、次のように起動できます。

docker start コンテナ名

Dev Containersが有効になっているか確認する

VSCodeの拡張機能画面から「Dev Containers」がインストールされ、有効になっているか確認します。

LinuxでDockerの権限エラーが発生する場合

Linuxでは、一般ユーザーからDockerを実行した際に権限エラーが発生する場合があります。

Dockerグループへユーザーを追加する方法として、次のコマンドがあります。

sudo usermod -aG docker $USER

設定反映には、ログアウト・ログインなどが必要になる場合があります。

ただし、Dockerグループへ所属すると、実質的にroot相当の強い操作権限を持つことになります。

共有サーバーやセキュリティ要件の高い環境では、安易に追加せず、運用ポリシーを確認することが重要です。

必要に応じてDocker Rootless Modeを検討する方法もあります。

WindowsとWSL 2を使用する場合の注意点

WindowsでDocker DesktopとWSL 2を利用している場合は、Docker Desktop側の設定も確認します。

主に次の項目です。

Use the WSL 2 based engine

また、Docker Desktopの設定から対象のLinuxディストリビューションに対するWSL Integrationが有効になっているか確認します。

WSL内のプロジェクトをDockerとVSCodeで扱う場合は、この設定が原因で接続できないことがあります。

Alpine Linuxを使用する場合の注意点

Alpine LinuxベースのコンテナにもDev Containersから接続できます。

ただし、一部のVSCode拡張機能はネイティブライブラリとしてglibcを必要とすることがあります。

Alpine Linuxは一般的にmusl libcを使用するため、そのような拡張機能が正常に動作しない場合があります。

問題が発生した場合は、Debian系やUbuntu系のイメージを検討すると解決する場合があります。

ただし、Alpine LinuxそのものがDev Containersで利用できないという意味ではありません。

VSCodeとDockerを組み合わせるメリット

VSCodeとDockerを組み合わせる最大のメリットは、開発環境を統一しやすいことです。

例えば、チーム全員で次の環境を共有できます。

Node.jsのバージョン
Pythonのバージョン
Linuxディストリビューション
VSCode拡張機能
OSパッケージ
ポート設定

ホストPCへ大量の開発ツールを直接インストールする必要も減らせます。

また、プロジェクトごとに開発環境を分離できます。

案件A
→ Node.js環境

案件B
→ Python環境

案件C
→ PHP環境

それぞれを別のDev Containerとして管理すれば、バージョン競合や環境差によるトラブルを減らせます。