Plugin dependencies - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A plugin dependency is another plugin that your plugin relies on, such as one whose MCP server or skill it calls. Each dependency tracks the latest version its marketplace provides unless you declare a version constraint, a semantic-version range such as ^2.0 or ~2.1.0 that you’ve tested against.
This page is for plugin authors who declare dependencies in plugin.json and for marketplace maintainers who tag releases. These cases are covered on other pages: Installing a plugin that has dependencies : see Manage installed plugins Reading a dependency error : see Dependency errors Declaring the npm and Bun packages that your plugin’s own code needs : see Node.js package dependencies To add a constraint, start at Declare a dependency with a version constraint .
If you maintain a plugin that others depend on, tag your releases so their constraints can resolve. Declare dependencies Without a version constraint, a dependency moves to each new release its marketplace publishes the next time users update. If that release renames an MCP tool your plugin calls, your plugin breaks for everyone who updates. With a constraint such as ~2.1.0 on a dependency from a git-backed source, users who have your plugin installed keep receiving 2.1.x patches of the dependency and never move to 2.2 .
To upgrade on your own schedule, test against a newer release and then publish a new version of your plugin 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 { "name" : "deploy-kit" , "version" : "3.1.0" , "dependencies" : [ "audit-logger" , { "name" : "secrets-vault" , "version" : "~2.1.0" } ] } An entry can be a string: the plugin name alone, such as "audit-logger" in this manifest, or "name@marketplace" to resolve it in another marketplace.
With a bare string, your plugin depends on whatever version that plugin’s marketplace provides. To set a version constraint, use an object with these fields, each a string: Field Description name The dependency’s plugin name, as it appears in its marketplace entry. Claude Code looks it up in the same marketplace as the declaring plugin unless you set marketplace . Required. version A semantic-version range such as ~2.1.0 , ^2.0 , >=1.4 , or =2.1.0 .
The dependency installs at the highest git tag that satisfies this range, so the dependency’s maintainer must tag releases . marketplace A different marketplace to resolve name in. An allowlist controls cross-marketplace dependencies, described in Depend on a plugin from another marketplace . A range doesn’t match pre-release versions such as 2.0.0-beta.1 unless you opt in with a pre-release suffix such as ^2.0.0-0 .
Bundle plugins for a team To let engineers install a curated set of plugins with one command, publish a plugin whose manifest contains a name and a dependencies array. A plugin manifest needs only name , so this is a valid plugin, and installing it installs every dependency. 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 plugin separately: .claude-plugin/plugin.json { "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" ] } To add a plugin to the standard set later, publish a new backend-standard version with the extra dependency.
When the marketplace doesn’t auto-update by default , engineers either turn on auto-update for the marketplace or update manually: Turn on auto-update for the marketplace : the next auto-update moves the bundle to the new version and installs any dependencies it adds. Update manually : run claude plugin update backend-standard in a shell, then /reload-plugins in an open session to install the newly added dependencies.
For the engineer-side steps, see Keep plugins updated . To deploy a bundle to everyone in an organization, an administrator adds it to enabledPlugins in managed settings. See Pre-install and require plugins . Depend on a plugin from another marketplace By default, Claude Code doesn’t install a dependency from a different marketplace than the declaring plugin’s own, unless the user already has that dependency installed and enabled at the same scope.
This default prevents one marketplace from silently installing plugins from a source the user hasn’t reviewed. To allow the install, add the target marketplace’s name to allowCrossMarketplaceDependenciesOn in the root marketplace’s marketplace.json . The root marketplace is the one that hosts the plugin the user is installing. Only the root marketplace’s allowlist applies. The following marketplace.json allows deploy-kit to depend on a plugin from your-shared-marketplace : .claude-plugin/marketplace.json { "name" : "your-marketplace" , "owner" : { "name" : "Your Org" }, "allowCrossMarketplaceDependenciesOn" : [ "your-shared-marketplace" ], "plugins" : [ { "name" : "deploy-kit" , "source" : "./deploy-kit" , "dependencies" : [ { "name" : "audit-logger" , "marketplace" : "your-shared-marketplace" } ] } ] } If allowCrossMarketplaceDependenciesOn is missing or doesn’t include the target marketplace, Claude Code doesn’t install the dependency.
When the dependency is declared in the marketplace entry, the install itself is refused with a message that starts Dependency "audit-logger@your-shared-marketplace" (required by deploy-kit@your-marketplace) is in marketplace "your-shared-marketplace", which is not in the allowlist and names the field to set. When it’s declared in plugin.json , the install completes without the dependency and your plugin then fails to load.
The allowlist check doesn’t apply to a dependency that is already enabled. If a user installs audit-logger from your-shared-marketplace themselves first, at the same scope, deploy-kit then installs without any change to the allowlist. Test a plugin and its dependency locally If you’re developing a plugin and the plugin it depends on at the same time, start Claude Code from your shell and load both with --plugin-dir : claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin The local copy of the dependency satisfies your plugin’s dependency entry, so you don’t need to install the dependency from its marketplace.
No version needed : the local plugin.json doesn’t need a version either, because a version constraint isn’t checked against a local copy. Entries that name a marketplace : an entry that names a marketplace also matches the local copy on Claude Code v2.1.242 or later. Until you install the dependency from its marketplace, your plugin stops loading whenever the local copy is disabled or absent: You disabled the local copy : your plugin is disabled at the next plugin load, with an error that ends is disabled — enable it or remove the dependency .
When the error names the dependency as <name>@inline , that identifier refers to the --plugin-dir copy. You started a session without the dependency’s --plugin-dir flag : the error reports the dependency as not installed. Pass the flag again, or install the dependency from its marketplace. When both plugins are in one parent folder, you can pass that folder to --plugin-dir once. If the folder isn’t itself a plugin, Claude Code loads each child folder that has a .claude-plugin/plugin.json .
Requires Claude Code v2.1.265 or later. Release a plugin that others depend on If you maintain a plugin that ot
The rest of this page is on the live site.