Skip to main content
A plugin can depend on other plugins by listing them in plugin.json or in its marketplace entry. By default, a dependency tracks the latest available version, so an upstream release can change the dependency under your plugin without warning. Version constraints let you hold a dependency at a tested version range until you choose to move. When you install a plugin that declares dependencies, Claude Code resolves and installs them automatically. If a dependency later goes missing, /reload-plugins and the background plugin auto-update reinstall it, provided its marketplace is already in your configured marketplaces. Re-running claude plugin install on the dependent plugin, or adding a marketplace with claude plugin marketplace add, also resolves any outstanding missing dependencies. Dependencies from a marketplace you have not added are left unresolved. This guide is for plugin authors who declare dependencies in plugin.json and for marketplace maintainers who tag releases. Dependencies here are other plugins; for the npm and Bun packages a plugin itself uses, see Node.js package dependencies. To install plugins that have dependencies, see Discover and install plugins. For the full manifest schema, see the Plugins reference.

​
Why constrain dependency versions

Consider an internal marketplace where two teams publish plugins. The platform team maintains secrets-vault, an MCP server that wraps a secrets backend. The deploy team maintains deploy-kit, which calls secrets-vault to fetch credentials during deploys. deploy-kit is tested against secrets-vault v2.1.0. Without a version constraint, the next time the platform team tags a release that renames an MCP tool, auto-update moves every engineer’s secrets-vault to the new version and deploy-kit breaks. With a version constraint, deploy-kit declares that it needs secrets-vault in the ~2.1.0 range. Engineers with deploy-kit installed stay on the highest matching 2.1.x patch. The deploy team upgrades on their own schedule by publishing a new deploy-kit version with a wider constraint.

​
Declare a dependency with a version constraint

List dependencies in the dependencies array of your plugin’s .claude-plugin/plugin.json. The following manifest declares one unversioned dependency and one constrained dependency:
.claude-plugin/plugin.json
An entry can be a bare string with only the plugin name, like "audit-logger" in the example above, which depends on whatever version that plugin’s marketplace provides. For more control, use an object with these fields: Pre-release versions such as 2.0.0-beta.1 are excluded unless your range opts in with a pre-release suffix like ^2.0.0-0.

​
Bundle plugins for a team

Besides the required name, a plugin manifest can consist of only a dependencies array. Installing it pulls in every dependency, which makes it a way to package a curated plugin set behind one install. For example, a platform team can publish role-specific bundles in an internal marketplace so engineers run one claude plugin install instead of installing each tool separately:
.claude-plugin/plugin.json