何が起きたか
VS Code拡張機能をインストールまたは有効化しようとしたとき、次のエラーが表示されました：
Extension '...' is not compatible with the current version of VS Code. Please update VS Code to use this extension.
拡張機能は無効のままか、インストールを拒否されました。原因はたいてい次の3つのうちのどれかです：
- VS Codeが古く、拡張機能が新しいエンジンを必要としている。
- VS Codeは最新だが、古いエンジン向けにビルドされた古いバージョンの拡張機能をインストールしている。
- VS Code Insiders（プレリリース版）を使用しており、拡張機能がまだ対応していない。
なぜこうなるのか
すべての拡張機能は、package.json に最小エンジンバージョンを宣言しています：
"engines": {
"vscode": "^1.85.0"
}
VS Codeはインストール時にこれを確認します。お使いのバージョンが拡張機能の要件より古い場合、インストールはブロックされます。
古い .vsix をサイドロードする場合は逆のパターンになります。たとえば VS Code 1.60向けにビルドされた拡張機能を取得した場合、1.85で削除されたAPIを呼び出す可能性があり、同じエラーが逆の形で発生します。
簡単な修正：VS Code をアップデートする
これで約90%のケースが解決します。VS Code内からアップデートを実行してください：
Windows / macOS
- コマンドパレットを開きます：Windows は
Ctrl+Shift+P、macOS はCmd+Shift+P。 - Update: Check for Updates と入力してEnterを押します。
- VS Codeがバックグラウンドでアップデートをダウンロードします。左下のボタンに Restart to Update と表示されたらクリックします。
Linux（ターミナル経由）
# Snap
sudo snap refresh code
# APT (official Microsoft repo)
sudo apt update && sudo apt install --only-upgrade code
# RPM/DNF
sudo dnf upgrade code
アップデートの確認
code --version
最初の行がバージョン番号です（例：1.91.0）。マーケットプレイスの拡張機能ページで確認してください。VS Code Engine フィールドに必要な最小バージョンが表示されています。
VS Code をアップデートできない場合
社内の管理されたマシンやCI環境では、アップデートが完全にブロックされていることがよくあります。回避策として、お使いのVS Codeに対応した古いバージョンの拡張機能をインストールします。
方法A — マーケットプレイスUIから特定バージョンをインストールする
- 拡張機能パネルを開きます（
Ctrl+Shift+X）。 - 拡張機能を検索し、名前をクリックして詳細ページを開きます。
- Install の横の小さな矢印をクリック → Install Another Version… を選択。
- お使いのVS Codeバージョンの制限以前にリリースされた最新バージョンを選択します。
方法B — .vsix をダウンロードしてサイドロードする
- marketplace.visualstudio.com の拡張機能ページにアクセスします。
- Version History をクリックし、互換性のある
.vsixファイルをダウンロードします。 - CLIからインストールします：
code --install-extension path/to/extension-1.2.3.vsix
または拡張機能パネルから：… メニューをクリック → Install from VSIX… を選択。
特殊なケース：VS Code Insiders
Insidersビルドは現在の安定版リリースより高い内部バージョン番号を持ちます。一部の拡張機能はまだ互換性を宣言していません。対処法は以下の通りです：
- そのプロジェクトでは安定版VS Codeチャンネルに切り替える。
- 拡張機能の作者がアップデートをリリースするまで待つ — Insidersで問題が起きた変更は通常1〜2週間以内にパッチが当たります。
- プレリリース拡張機能を有効にする：拡張機能詳細ページで Switch to Pre-Release Version を切り替えます。
恒久的な修正：VS Code の自動更新を維持する
一度設定を変更するだけで、この問題の再発を防ぐことができます：
- 設定を開きます：
Ctrl+,（macOSはCmd+,）。 - update mode を検索します。
- Update: Mode を
defaultに設定します — バックグラウンドで静かにダウンロードし、再起動を促します。
または settings.json に直接記述します：
{
"update.mode": "default"
}
有効な値：none、manual、start、default。バージョンを固定する特別な理由がない限り、default を使用してください。
修正の確認
VS Codeのアップデートまたは互換性のある拡張機能バージョンのインストール後：
- 拡張機能パネルを開きます（
Ctrl+Shift+X）。 - 拡張機能が警告バッジなしで Enabled と表示されているはずです。
- 出力パネル（
Ctrl+Shift+U、Extension Host を選択）で残存するエラーを確認します。 - 拡張機能の主要機能を実行してみてください — 動作すれば完了です。
まだ非互換と表示される場合は、Help → Toggle Developer Tools からデベロッパーツールを開いてください。Consoleタブに失敗した正確なAPI呼び出しが表示されます — 表面的なエラーメッセージよりはるかに有用な情報です。
まとめ
- ほとんどの場合：VS Code をアップデートする（
code --versionで現在のバージョンを確認）。 - アップデートできない場合：Install Another Version… またはダウンロードした
.vsixで古い拡張機能バージョンをインストールする。 - Insidersの場合：プレリリース拡張機能チャンネルを試すか、安定版に切り替える。
- 長期的な対策：設定で
update.modeをdefaultに設定する。