プラグイン依存関係のバージョンを制約する

プラグイン依存関係のバージョン制約を宣言して、キュレーションされたプラグインセットを 1 つのインストールの背後にバンドルします。

プラグインは、plugin.json またはマーケットプレイスエントリにリストすることで、他のプラグインに依存できます。デフォルトでは、依存関係は最新の利用可能なバージョンを追跡するため、アップストリームリリースは警告なしにプラグインの依存関係を変更できます。バージョン制約を使用すると、移動を選択するまで、依存関係をテスト済みのバージョン範囲に保つことができます。

依存関係を宣言するプラグインをインストールすると、Claude Code は依存関係を自動的に解決してインストールします。ただし、マーケットプレイスエントリに command ソースまたは headersHelper がある依存関係は、最初に自分でインストールします。その後、/reload-plugins、依存プラグインのマーケットプレイスの自動更新、依存プラグインで claude plugin install を再実行、および claude plugin marketplace add は、同じルールの下で、まだインストールされていない宣言された依存関係をインストールします。1 つが未解決のままの場合は、依存関係エラーを解決するを参照してください。

このガイドは、plugin.json で依存関係を宣言するプラグイン作成者と、リリースにタグを付けるマーケットプレイス保守者向けです。ここでの依存関係は他のプラグインです。プラグイン自体が使用する npm および Bun パッケージについては、Node.js パッケージ依存関係を参照してください。依存関係を持つプラグインをインストールするには、プラグインの検出とインストールを参照してください。完全なマニフェストスキーマについては、プラグインリファレンスを参照してください。

依存関係のバージョンを制約する理由

2 つのチームがプラグインを公開する内部マーケットプレイスを考えてみてください。プラットフォームチームは、シークレットバックエンドをラップする MCP サーバーである secrets-vault を保守しています。デプロイチームは、デプロイ中に認証情報を取得するために secrets-vault を呼び出す deploy-kit を保守しています。

deploy-kit は secrets-vault v2.1.0 に対してテストされています。バージョン制約がない場合、プラットフォームチームが MCP ツールの名前を変更するリリースにタグを付けると、次回の自動更新により、すべてのエンジニアの secrets-vault が新しいバージョンに移動し、deploy-kit が破損します。

バージョン制約を使用すると、deploy-kit は secrets-vault が ~2.1.0 範囲内にあることが必要であることを宣言します。deploy-kit がインストールされているエンジニアは、最高の一致する 2.1.x パッチに留まります。デプロイチームは、より広い制約を持つ新しい deploy-kit バージョンを公開することで、独自のスケジュールでアップグレードします。

バージョン制約を使用して依存関係を宣言する

プラグインの .claude-plugin/plugin.json の dependencies 配列に依存関係をリストします。

次のマニフェストは、1 つのバージョン指定なしの依存関係と 1 つの制約付き依存関係を宣言しています。

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

エントリは、deploy-kit マニフェストの "audit-logger" のようにプラグイン名のみを含む単純な文字列にすることができます。これは、そのプラグインのマーケットプレイスが提供するバージョンに依存します。より詳細に制御するには、次のフィールドを持つオブジェクトを使用します。

フィールド	型	説明
`name`	string	プラグイン名。宣言するプラグインと同じマーケットプレイス内で解決されます。必須。
`version`	string	`~2.1.0`、`^2.0`、`>=1.4`、または `=2.1.0` などの semver 範囲。依存関係は、この範囲を満たす最高のタグ付きバージョンで取得されます。
`marketplace`	string	`name` を解決する別のマーケットプレイス。クロスマーケットプレイス依存関係は、ターゲットマーケットプレイスがルートマーケットプレイスの `marketplace.json` の `allowCrossMarketplaceDependenciesOn` にリストされていない限り、ブロックされます。

2.0.0-beta.1 などのプレリリースバージョンは、^2.0.0-0 のようなプレリリースサフィックスで範囲がオプトインしない限り、除外されます。

チームのプラグインをバンドルする

必須の name の他に、プラグインマニフェストは dependencies 配列のみで構成することができます。これをインストールすると、すべての依存関係がプルされます。これにより、キュレーションされたプラグインセットを 1 つのインストールの背後にパッケージ化する方法になります。

例えば、プラットフォームチームは内部マーケットプレイスでロール固有のバンドルを公開できるため、エンジニアは各ツールを個別にインストールする代わりに、1 つの claude plugin install を実行できます。

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

backend-standard をインストールすると、4 つの依存関係すべてが解決され、インストールされます。

後で標準セットにツールを追加するには、追加の依存関係を含む新しい backend-standard バージョンを公開します。マーケットプレイスが自動更新しない限り、エンジニアは次の 2 つの方法のいずれかで新しいバージョンを取得します。

/plugin でマーケットプレイスの自動更新を有効にします。次の自動更新でバンドルが新しいバージョンに移動し、追加される依存関係がインストールされます。
claude plugin update backend-standard を実行してから、/reload-plugins を実行して、新しく追加された依存関係をインストールします。

バンドルを組織全体にロールアウトするには、管理設定の enabledPlugins にバンドルプラグインを追加します。

別のマーケットプレイスからプラグインに依存する

デフォルトでは、Claude Code は、それを宣言するプラグインとは異なるマーケットプレイスに存在する依存関係の自動インストールを拒否します。これにより、1 つのマーケットプレイスが、確認していないソースからプラグインを静かにプルインするのを防ぎます。

これを許可するには、ルートマーケットプレイスの保守者が、ターゲットマーケットプレイス名を marketplace.json の allowCrossMarketplaceDependenciesOn に追加します。ルートマーケットプレイスは、ユーザーがインストールしているプラグインをホストするマーケットプレイスです。そのアローリストのみが参照されるため、信頼は中間マーケットプレイスを通じてチェーンされません。

次の marketplace.json は、deploy-kit が acme-shared からプラグインに依存することを許可しています。

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

フィールドが欠落しているか、ターゲットマーケットプレイスが含まれていない場合、インストールは cross-marketplace エラーで失敗し、設定するフィールドに名前を付けます。ユーザーは依然として依存関係を手動で最初にインストールできます。これにより、アローリストを変更することなく制約が満たされます。

プラグインとその依存関係をローカルでテストする

プラグインとそれが依存するプラグインを同時に開発している場合は、--plugin-dir で両方をロードします。

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

依存関係のローカルコピーは、エントリがマーケットプレイスを指定している場合でも、プラグインの依存関係エントリを満たします。そのため、マーケットプレイスから依存関係をインストールする必要はありません。Claude Code は、ローカルコピーに対してバージョン制約をチェックしないため、ローカルの plugin.json には version が不要です。v2.1.242 より前では、マーケットプレイスを指定する依存関係エントリはローカルコピーと一致せず、Claude Code はロード時にプラグインを無効にしていました。

両方のプラグインが 1 つの親フォルダに存在する場合、そのフォルダを --plugin-dir に 1 回渡すことができます。フォルダ自体がプラグインでない場合、Claude Code は .claude-plugin/plugin.json を持つ各子フォルダをロードします。Claude Code v2.1.265 以降が必要です。

マーケットプレイスから依存関係をインストールしていない場合、ローカルコピーがなくなるとプラグインのロードが停止します。

ローカルコピーを無効にした場合: Claude Code は次のプラグインロード時にプラグインを無効にします。マーケットプレイスを指定する依存関係エントリの場合、Claude Code は Dependency "<name>@inline" is disabled — enable it or remove the dependency と報告します。ベアネームエントリの場合は、依存関係をベアネームで報告します。<name>@inline は、Claude Code がすべての --plugin-dir および --plugin-url プラグインを識別する方法です。
依存関係の --plugin-dir フラグなしでセッションを開始した場合: Claude Code は依存関係がインストールされていないと報告します。フラグを再度渡すか、マーケットプレイスから依存関係をインストールしてください。

バージョン解決のためのタグプラグインリリース

Claude Code は、依存関係をホストするリポジトリの git タグに対してバージョン制約を解決します。プラグイン自体のリポジトリ（github、url、git-subdir プラグインソースの場合）、またはマーケットプレイスが相対パスで参照するプラグインのマーケットプレイスリポジトリです。Claude Code が依存関係の利用可能なバージョンを見つけるには、アップストリームプラグインのリリースが特定の命名規則を使用してタグ付けされている必要があります。

各リリースを {plugin-name}--v{version} としてタグ付けします。ここで {version} はそのコミットの plugin.json の version フィールドと一致します。プラグインディレクトリから、以下を実行します。

claude plugin tag --push

claude plugin tag コマンドは、プラグインのマニフェストと囲まれたマーケットプレイスエントリからタグ名を導出します。タグを作成する前に、プラグインの内容を検証し、plugin.json とマーケットプレイスエントリがバージョンについて一致していることを確認し、プラグインディレクトリの下でクリーンな作業ツリーを要求し、タグが既に存在する場合は拒否します。

--push は origin リモートにタグをプッシュするため、リポジトリは設定済みの origin リモートが必要です。別のリモートにプッシュするには --remote を渡します。
プッシュが失敗した場合、タグはローカルで作成され、コマンドはエラーで終了します。
--push を使用すると、成功した実行は Created tag secrets-vault--v2.1.0 と Pushed to origin で終了します。最後の行はプッシュ先のリモートを名前で示します。--push なしでは、コマンドは代わりに実行する git push コマンドを出力します。
--dry-run は、タグを作成せずにタグ付けされるものを出力します。

git tag secrets-vault--v2.1.0 を直接実行することは、plugin.json とマーケットプレイスエントリを自分で同期させておけば同等です。

プラグイン名プレフィックスにより、1 つのマーケットプレイスリポジトリが独立したバージョン行を持つ複数のプラグインをホストできます。--v セパレータは完全なプラグイン名のプレフィックスマッチとして解析されるため、ハイフンを含むプラグイン名は正しく処理されます。

{ "name": "secrets-vault", "version": "~2.1.0" } を宣言するプラグインをインストールすると、Claude Code は secrets-vault をホストするリポジトリのタグをリストし、secrets-vault--v で始まるものにフィルタリングし、~2.1.0 を満たす最高バージョンを取得します。プラグイン自体のリポジトリのタグが範囲を満たさない場合、インストールは Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0 で失敗します。これは依存関係をそのマーケットプレイスと共に名前で示します。一致するタグのない相対パスプラグインの場合、Claude Code はマーケットプレイスの現在のコピーをインストールし、プラグインが読み込まれるときに制約をチェックします。

マーケットプレイスが相対パスで参照するプラグインの場合、ローカルフォルダパスとして追加されたマーケットプレイスは、フォルダが git リポジトリの場合、同じ方法でタグを解決します。これには Claude Code v2.1.196 以降が必要です。2 つのケースでは Claude Code はフォルダの現在の内容から依存関係をインストールします。

以前のバージョンはローカルフォルダマーケットプレイスからタグを読み取らないため、制約付き依存関係はそのコピーが範囲を満たす場合にのみ読み込まれます。
git リポジトリではないローカルフォルダには、バージョンに関係なくタグがありません。

解決されたタグの semver は plugin.json の version とは別に記録されるため、制約チェックは plugin.json がそのコミットで古い値を持っている場合でも、実際に取得されたタグを使用します。タグ解決インストールのキャッシュディレクトリ名には 12 文字のコミット SHA サフィックスが含まれるため、メンテナーがタグを別のコミットに強制移動した場合、次のインストールは古いコンテンツを再利用する代わりに新しいキャッシュディレクトリを取得します。

Note

npm、archive、または command プラグインソースを持つ依存関係の場合、タグベースの解決は git バックアップソースにのみ適用されるため、制約はどのバージョンが取得されるかを制御しません。制約は読み込み時にもチェックされ、インストールされたバージョンが制約を満たさない場合、依存プラグインは dependency-version-unsatisfied で無効になります。command ソースの場合、Claude Code は依存関係の plugin.json のバージョンをチェックし、コンテンツハッシュサフィックスを無視します。plugin.json がバージョンを設定しない依存関係は制約を満たさないため、制約する前に設定してください。

Claude Code は command ソースを持つ依存関係自体をインストールしないため、ユーザーは最初にそれをインストールします。Claude Code は依存関係のマーケットプレイスエントリで headersHelper を実行しないため、ユーザーは最初にそのプラグインをインストールします。

制約がどのように相互作用するか

複数のインストール済みプラグインが同じ依存関係を制約する場合、Claude Code はそれらの範囲を交差させ、依存関係をすべての範囲を満たす最高バージョンに解決します。下の表は、一般的な組み合わせがどのように解決されるかを示しています。

プラグイン A が必要	プラグイン B が必要	結果
`^2.0`	`>=2.1`	`2.1.0` 以上の最高 `2.x` タグで 1 つのインストール。両方のプラグインが読み込まれます。
`~2.1`	`~3.0`	プラグイン B のインストールが `range-conflict` で失敗します。プラグイン A と依存関係は以前のままです。
`=2.1.0`	なし	依存関係は `2.1.0` に留まります。プラグイン A がインストールされている間、自動更新は新しいバージョンをスキップします。

自動更新は、制約付き依存関係を、マーケットプレイスの最新バージョンではなく、インストール済みプラグインのすべての範囲を満たす最高 git タグで取得するため、依存関係は許可された範囲内で更新を受け続けます。すべての範囲を満たすタグがない場合、自動更新はその依存関係をスキップし、スキップを /plugin エラータブに表示し、制約するプラグインに名前を付けます。

依存関係を制約する最後のプラグインをアンインストールすると、依存関係は保持されなくなり、次の更新でマーケットプレイスエントリの追跡を再開します。

依存関係を持つプラグインを有効または無効にする

このセクションでは、マーケットプレイスからインストールされたプラグインについて説明します。--plugin-dir で読み込んだコピーについては、プラグインとその依存関係をローカルでテストするを参照してください。

プラグインを有効にすると、それが依存するプラグインも有効になり、別の有効なプラグインがまだそれを必要としている場合、プラグインを無効にすることはブロックされます。

プラグインを有効にすると、Claude Code は同じスコープでその依存関係も有効にします。依存関係が独自の依存関係を持つ場合、Claude Code はそれらも有効にします。成功メッセージは、名前を付けたプラグインと一緒に有効になったものをリストします。依存関係を有効にできない場合、コマンドは拒否され、何がブロックしているか、およびそれを修正する方法が表示されます。

条件	結果
依存関係がインストールされていない	有効化が失敗し、各欠落している依存関係の `claude plugin install` コマンドを出力します。
依存関係が組織のプラグインポリシーによってブロックされている	有効化が失敗し、ブロックされた依存関係に名前を付けます。
依存関係が、ターゲットスコープより優先度の高いスコープで `false` に設定されている	有効化が失敗します。そのスコープで依存関係を有効にするか、`--scope` を渡してそこに書き込みます。
すべての依存関係がインストールされ、許可されている	有効化が成功し、プラグインと、ターゲットスコープでまだ有効になっていない各依存関係に対して `true` を書き込みます。

これは、依存関係がマニフェストで defaultEnabled: false を設定している場合でも当てはまります。Claude Code はそれに対して明示的な true を書き込むためです。同じことがインストール時にも適用されます。アクティブなプラグインを満たすために取得された依存関係は、独自のデフォルトに関係なく true でインストールされます。

プラグインを無効にすると、別の有効なプラグインがまだそれに依存している場合、Claude Code は拒否します。エラーはそれに依存するプラグインに名前を付け、正しい順序でそれらを無効にする連鎖コマンドを提供します。

たとえば、deploy-kit が secrets-vault に依存している場合、secrets-vault だけを無効にすると、次のような出力で失敗します。

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

エラーから連鎖コマンドをコピーして、1 つのステップで完全なセットを無効にします。

孤立した自動インストール依存関係を削除する

自動インストール依存関係は、それらをインストールしたプラグインがアンインストールされた後もディスク上に留まります。これは、依存プラグインを再インストールしたい場合や、依存関係を直接使用し続けたい場合に備えてです。それらをクリーンアップするには、claude plugin prune を実行して、インストール済みプラグインがもう必要としない自動インストール依存関係をリストし、確認プロンプトの後に削除します。

claude plugin prune

削除対象がない場合、コマンドは Nothing to prune と理由を出力して終了します。これは新規インストール時の予想される出力であり、エラーではありません。

デフォルトでは、prune はユーザースコープで動作し、何かを削除する前に確認を求めます。

--scope project または --scope local は別のスコープをターゲットにします。
--dry-run は削除されるものをリストし、何も変更しません。
-y は確認プロンプトをスキップします。stdin または stdout がターミナルでない場合、prune は孤立したものをリストして終了し、-y を渡さない限り削除しません。

アンインストールの一部として prune するには、claude plugin uninstall に --prune を渡します。名前付きプラグインを削除した後、Claude Code は自動インストール依存関係をスキャンして、現在孤立しているものを削除します。自分でインストールしたプラグインは決して prune されません。別のプラグインの dependencies 配列を通じて自動的にインストールされたものだけです。

同じ確認動作が適用されます。stdin または stdout がターミナルでない場合、アンインストールは完了しますが、prune ステップは孤立したものをリストし、-y を渡さない限り削除しません。

たとえば、deploy-kit をアンインストールし、それが残す依存関係をクリーンアップするには、以下を実行します。

claude plugin uninstall deploy-kit --prune

依存関係エラーを解決する

依存関係の問題は、claude plugin list と /plugin インターフェイスに表示されます。これらはこの表の文字通りのコードではなく、説明的なエラーメッセージとして表示されます。Claude Code は、エラーを解決するまで影響を受けたプラグインを無効にします。以下の表は、最も一般的なエラーとその解決方法を示しています。

エラー	意味	解決方法
`dependency-unsatisfied`	宣言された依存関係がインストールされていないか、インストールされていますが無効になっています。	エラーメッセージに表示されている `claude plugin install` コマンドを実行してください。依存関係のマーケットプレイスがまだ設定されていない場合は、`claude plugin marketplace add` で追加すると、Claude Code が依存関係を自動的に解決します。依存関係が無効になっている場合は、有効にしてください。
`range-conflict`	依存関係のバージョン要件を組み合わせることができません。エラーメッセージは原因に名前を付けます。バージョンがすべての範囲を満たさない、範囲が有効な semver 構文ではない、または結合された範囲が複雑すぎて交差できません。	競合するプラグインの 1 つをアンインストールまたは更新し、無効な `version` 文字列を修正し、長い `\|\|` チェーンを簡略化するか、アップストリーム作成者に制約を広げるよう依頼してください。
`dependency-version-unsatisfied`	インストール済み依存関係のバージョンがこのプラグインの宣言された範囲外です。	`claude plugin install <dependency>@<marketplace>` を実行して、すべての現在の制約に対して依存関係を再解決します。
`no-matching-tag`	依存関係のリポジトリに、範囲を満たす `{name}--v*` タグがありません。	アップストリームが上記の規則を使用してリリースにタグを付けていることを確認するか、範囲を緩和してください。

これらのエラーをプログラムで確認するには、claude plugin list --json を実行してください。問題のあるプラグインには、それらをリストする errors フィールドが含まれます。正常に読み込まれたプラグインはこのフィールドを省略します。

plugin-dependencies.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

プラグイン依存関係のバージョンを制約する

依存関係のバージョンを制約する理由

バージョン制約を使用して依存関係を宣言する

チームのプラグインをバンドルする

別のマーケットプレイスからプラグインに依存する

プラグインとその依存関係をローカルでテストする

バージョン解決のためのタグプラグインリリース

制約がどのように相互作用するか

依存関係を持つプラグインを有効または無効にする

孤立した自動インストール依存関係を削除する

依存関係エラーを解決する

関連項目

plugin-dependencies.md +4 −4