Skip to main content
Un plugin peut dépendre d’autres plugins en les listant dans plugin.json ou dans son entrée marketplace. Par défaut, une dépendance suit la dernière version disponible, donc une version en amont peut modifier la dépendance sans avertissement. Les contraintes de version vous permettent de maintenir une dépendance à une plage de version testée jusqu’à ce que vous décidiez de la mettre à jour. Lorsque vous installez un plugin qui déclare des dépendances, Claude Code les résout et les installe automatiquement, à l’exception d’une dépendance dont l’entrée marketplace a une command source ou une headersHelper, que vous installez vous-même en premier. Par la suite, /reload-plugins, la mise à jour automatique du marketplace du plugin dépendant, la réexécution de claude plugin install sur le plugin dépendant, et claude plugin marketplace add installent chacun toute dépendance déclarée qui n’est pas encore installée, selon les mêmes règles ; si l’une reste non résolue, consultez Résoudre les erreurs de dépendance. Ce guide est destiné aux auteurs de plugins qui déclarent des dépendances dans plugin.json et aux responsables de marketplace qui balisent les versions. Les dépendances ici sont d’autres plugins ; pour les packages npm et Bun qu’un plugin utilise lui-même, consultez Dépendances de packages Node.js. Pour installer des plugins qui ont des dépendances, consultez Découvrir et installer des plugins. Pour le schéma de manifeste complet, consultez la Référence des plugins.

​
Pourquoi contraindre les versions des dépendances

Considérez un marketplace interne où deux équipes publient des plugins. L’équipe plateforme maintient secrets-vault, un serveur MCP qui encapsule un backend de secrets. L’équipe de déploiement maintient deploy-kit, qui appelle secrets-vault pour récupérer les identifiants lors des déploiements. deploy-kit est testé contre secrets-vault v2.1.0. Sans contrainte de version, la prochaine fois que l’équipe plateforme balisera une version qui renomme un outil MCP, la mise à jour automatique déplacera chaque secrets-vault de l’ingénieur vers la nouvelle version et deploy-kit se cassera. Avec une contrainte de version, deploy-kit déclare qu’il a besoin de secrets-vault dans la plage ~2.1.0. Les ingénieurs avec deploy-kit installé restent sur le correctif 2.1.x le plus élevé correspondant. L’équipe de déploiement effectue la mise à niveau selon son propre calendrier en publiant une nouvelle version de deploy-kit avec une contrainte plus large.

​
Déclarer une dépendance avec une contrainte de version

Listez les dépendances dans le tableau dependencies du plugin.json de votre plugin. Le manifeste suivant déclare une dépendance sans version et une dépendance contrainte :
.claude-plugin/plugin.json
Une entrée peut être une simple chaîne avec uniquement le nom du plugin, comme "audit-logger" dans l’exemple ci-dessus, qui dépend de la version que le marketplace de ce plugin fournit. Pour plus de contrôle, utilisez un objet avec ces champs : Les versions de pré-version telles que 2.0.0-beta.1 sont exclues sauf si votre plage opte pour un suffixe de pré-version comme ^2.0.0-0.

​
Regrouper les plugins pour une équipe

En plus du name obligatoire, un manifeste de plugin peut se composer uniquement d’un tableau dependencies. Son installation récupère chaque dépendance, ce qui en fait un moyen de regrouper un ensemble de plugins curatisé derrière une seule installation. Par exemple, une équipe de plateforme peut publier des bundles spécifiques à un rôle dans une marketplace interne afin que les ingénieurs exécutent une seule commande claude plugin install au lieu d’installer chaque outil séparément :
.claude-plugin/plugin.json
L’installation de backend-standard résout et installe les quatre dépendances. Pour ajouter un outil à l’ensemble standard ultérieurement, publiez une nouvelle version de backend-standard avec la dépendance supplémentaire. La mise à jour automatique est désactivée par défaut pour les marketplaces non-Anthropic, donc les ingénieurs récupèrent la nouvelle version de l’une des deux façons suivantes :
  • Activez la mise à jour automatique pour la marketplace dans /plugin. La prochaine mise à jour automatique déplace le bundle vers la nouvelle version et installe les dépendances qu’il ajoute.
  • Exécutez claude plugin update backend-standard, puis /reload-plugins pour installer les dépendances nouvellement ajoutées.
Pour déployer les bundles dans toute une organisation, ajoutez le plugin bundle à enabledPlugins dans les paramètres gérés.

​
Dépendre d’un plugin d’un autre marketplace

Par défaut, Claude Code refuse d’installer automatiquement une dépendance qui se trouve dans un marketplace différent de celui du plugin qui la déclare. Cela empêche un marketplace de silencieusement extraire des plugins d’une source que vous n’avez pas examinée. Pour l’autoriser, le responsable du marketplace racine ajoute le nom du marketplace cible à allowCrossMarketplaceDependenciesOn dans marketplace.json. Le marketplace racine est celui qui héberge le plugin que l’utilisateur installe ; seule sa liste d’autorisation est consultée, donc la confiance ne s’enchaîne pas à travers les marketplaces intermédiaires. Le marketplace.json suivant permet à deploy-kit de dépendre d’un plugin de acme-shared :
.claude-plugin/marketplace.json
Si le champ est manquant ou n’inclut pas le marketplace cible, l’installation échoue avec une erreur cross-marketplace nommant le champ à définir. Les utilisateurs peuvent toujours installer la dépendance manuellement en premier, ce qui satisfait la contrainte sans modifier la liste d’autorisation.

​
Tester un plugin et sa dépendance localement

Si vous développez un plugin et le plugin dont il dépend en même temps, chargez les deux avec --plugin-dir :
La copie locale de la dépendance satisfait l’entrée de dépendance de votre plugin, même quand l’entrée nomme une marketplace, donc vous n’avez pas besoin d’installer la dépendance depuis sa marketplace. Claude Code ne vérifie pas une contrainte de version par rapport à une copie locale, donc le plugin.json local n’a pas besoin d’une version. Avant la v2.1.242, une entrée de dépendance qui nommait une marketplace ne correspondait jamais à la copie locale, et Claude Code désactivait votre plugin au chargement. Quand les deux plugins se trouvent dans un dossier parent unique, vous pouvez passer ce dossier à --plugin-dir une seule fois. Si le dossier n’est pas lui-même un plugin, Claude Code charge chaque dossier enfant qui a un .claude-plugin/plugin.json. Nécessite Claude Code v2.1.265 ou ultérieur. Si vous n’avez pas installé la dépendance depuis sa marketplace, votre plugin arrête de se charger quand la copie locale disparaît :
  • Vous avez désactivé la copie locale : Claude Code désactive votre plugin au prochain chargement de plugin. Pour une entrée de dépendance qui nomme une marketplace, Claude Code rapporte Dependency "<name>@inline" is disabled — enable it or remove the dependency ; pour une entrée de nom simple, il rapporte la dépendance par son nom simple. <name>@inline est comment Claude Code identifie chaque plugin --plugin-dir et --plugin-url.
  • Vous avez démarré une session sans le drapeau --plugin-dir de la dépendance : Claude Code rapporte la dépendance comme non installée. Passez le drapeau à nouveau, ou installez la dépendance depuis sa marketplace.

​
Versions des plugins de balises pour la résolution de version

Claude Code résout les contraintes de version par rapport aux balises git du référentiel qui héberge la dépendance : le référentiel propre du plugin pour les sources de plugin github, url et git-subdir, ou le référentiel de la marketplace pour un plugin que la marketplace référence par un chemin relatif. Pour que Claude Code trouve les versions disponibles d’une dépendance, les versions du plugin en amont doivent être balisées en utilisant une convention de nommage spécifique. Balisez chaque version comme {plugin-name}--v{version}, où {version} correspond au champ version dans le plugin.json de ce commit. À partir du répertoire du plugin, exécutez :
La commande claude plugin tag dérive le nom de la balise du manifeste du plugin et de l’entrée de la marketplace qui l’entoure. Avant de créer la balise, elle valide le contenu du plugin, vérifie que plugin.json et l’entrée de la marketplace s’accordent sur la version, exige un arbre de travail propre sous le répertoire du plugin, et refuse si la balise existe déjà.
  • --push pousse la balise vers la télécommande origin, donc le référentiel a besoin d’une télécommande origin configurée. Passez --remote pour pousser vers une autre.
  • Si la poussée échoue, la balise est toujours créée localement et la commande se termine avec une erreur.
  • Avec --push, une exécution réussie se termine par Created tag secrets-vault--v2.1.0 et Pushed to origin, où la dernière ligne nomme la télécommande vers laquelle elle a été poussée. Sans --push, la commande affiche la commande git push à exécuter à la place.
  • --dry-run affiche ce qui serait balisé sans le créer.
L’exécution de git tag secrets-vault--v2.1.0 directement est équivalente si vous gardez plugin.json et l’entrée de la marketplace synchronisés vous-même. Le préfixe du nom du plugin permet à un référentiel de marketplace d’héberger plusieurs plugins avec des lignes de version indépendantes. Le séparateur --v est analysé comme une correspondance de préfixe sur le nom complet du plugin, donc les noms de plugin qui contiennent des traits d’union sont gérés correctement. Lorsque vous installez un plugin qui déclare { "name": "secrets-vault", "version": "~2.1.0" }, Claude Code répertorie les balises du référentiel qui héberge secrets-vault, filtre celles commençant par secrets-vault--v, et récupère la version la plus élevée satisfaisant ~2.1.0. Si aucune balise du référentiel propre du plugin ne satisfait la plage, l’installation échoue avec Dependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0, qui nomme la dépendance avec sa marketplace. Pour un plugin avec chemin relatif sans balise correspondante, Claude Code installe la copie actuelle de la marketplace à la place et vérifie la contrainte lors du chargement du plugin. Pour un plugin que la marketplace référence par un chemin relatif, une marketplace ajoutée comme chemin de dossier local résout les balises de la même manière lorsque le dossier est un référentiel git. Cela nécessite Claude Code v2.1.196 ou ultérieur. Dans deux cas, Claude Code installe la dépendance à partir du contenu actuel du dossier à la place :
  • Les versions antérieures ne lisent pas les balises d’une marketplace de dossier local, donc une dépendance contrainte se charge uniquement si cette copie satisfait la plage.
  • Un dossier local qui n’est pas un référentiel git n’a pas de balises, quelle que soit la version.
Le semver de la balise résolue est enregistré séparément de la version du plugin.json, donc les vérifications de contrainte utilisent la balise qui a été réellement récupérée même si la version du plugin.json à ce commit a une valeur obsolète. Le nom du répertoire de cache pour une installation résolue par balise inclut un suffixe SHA de commit de 12 caractères, donc si un responsable force-déplace une balise vers un commit différent, l’installation suivante obtient un répertoire de cache frais au lieu de réutiliser du contenu obsolète.
Pour les dépendances avec une source de plugin npm, archive ou command, la contrainte ne contrôle pas quelle version est récupérée, puisque la résolution basée sur les balises s’applique uniquement aux sources sauvegardées par git. La contrainte est toujours vérifiée au moment du chargement, et le plugin dépendant est désactivé avec dependency-version-unsatisfied si la version installée ne la satisfait pas. Pour une source command, Claude Code vérifie la version dans le plugin.json de la dépendance et ignore le suffixe de hachage de contenu ; une dépendance dont le plugin.json ne définit pas de version ne satisfait aucune contrainte, donc définissez-en une avant de la contraindre.Claude Code n’installe jamais lui-même une dépendance avec une source command, donc les utilisateurs l’installent d’abord. Claude Code n’exécute jamais non plus le headersHelper sur l’entrée de la marketplace d’une dépendance, donc les utilisateurs installent d’abord ce plugin.

​
Comment les contraintes interagissent

Lorsque plusieurs plugins installés contraignent la même dépendance, Claude Code intersecte leurs plages et résout la dépendance à la version la plus élevée qui satisfait tous les critères. Le tableau ci-dessous montre comment les combinaisons courantes se résolvent. La mise à jour automatique récupère une dépendance contrainte à la balise git la plus élevée qui satisfait la plage de chaque plugin installé, plutôt qu’à la dernière version du marketplace, de sorte que la dépendance continue à recevoir des mises à jour dans sa plage autorisée. Si aucune balise ne satisfait toutes les plages, la mise à jour automatique ignore cette dépendance et répertorie l’ignorance dans l’onglet Erreurs de /plugin, en nommant le plugin contraignant. Lorsque vous désinstallez le dernier plugin qui contraint une dépendance, la dépendance n’est plus maintenue et reprend le suivi de son entrée marketplace lors de la prochaine mise à jour.

​
Activer ou désactiver un plugin avec des dépendances

Cette section couvre les plugins installés à partir d’une marketplace. Pour une copie que vous avez chargée avec --plugin-dir, voir Tester un plugin et sa dépendance localement. L’activation d’un plugin active également les plugins dont il dépend, et la désactivation d’un plugin est bloquée si un autre plugin activé en a toujours besoin. Lorsque vous activez un plugin, Claude Code active également ses dépendances au même scope. Si une dépendance a ses propres dépendances, Claude Code les active également. Le message de succès liste ce qui d’autre a été activé avec le plugin que vous avez nommé. Si une dépendance ne peut pas être activée, la commande refuse et vous dit ce qui bloque et comment corriger : Ceci s’applique même lorsqu’une dépendance définit defaultEnabled: false dans son manifeste, car Claude Code écrit un true explicite pour celle-ci. La même chose s’applique à l’installation : une dépendance extraite pour satisfaire un plugin actif s’installe avec true indépendamment de sa propre valeur par défaut. Lorsque vous désactivez un plugin, Claude Code refuse si un autre plugin activé en dépend toujours. L’erreur nomme les plugins qui en dépendent et vous donne une commande chaînée qui les désactive dans le bon ordre, se terminant par celui que vous avez demandé. Par exemple, si deploy-kit dépend de secrets-vault, la désactivation de secrets-vault seule échoue avec une sortie similaire à ce qui suit :
Copiez la commande chaînée de l’erreur pour désactiver l’ensemble complet en une seule étape.

​
Supprimer les dépendances auto-installées orphelines

Les dépendances auto-installées restent sur le disque après la désinstallation des plugins qui les ont installées, au cas où vous réinstalliez un plugin dépendant ou souhaiteriez continuer à utiliser la dépendance directement. Pour les nettoyer, exécutez claude plugin prune pour lister les dépendances auto-installées qui n’ont plus aucun plugin installé les exigeant et les supprimer après une invite de confirmation.
Si rien ne se qualifie pour la suppression, la commande affiche Nothing to prune avec la raison et se termine. C’est le résultat attendu sur une installation récente, pas une erreur. Par défaut, prune fonctionne à la portée utilisateur et demande une confirmation avant de supprimer quoi que ce soit :
  • --scope project ou --scope local cible une portée différente.
  • --dry-run liste ce qui serait supprimé sans rien modifier.
  • -y ignore l’invite de confirmation. Lorsque stdin ou stdout n’est pas un terminal, prune liste les orphelins et se termine sans les supprimer sauf si vous passez -y.
Pour nettoyer dans le cadre d’une désinstallation, passez --prune à claude plugin uninstall. Après suppression du plugin nommé, Claude Code analyse et supprime toute dépendance auto-installée qui est maintenant orpheline. Les plugins que vous avez installés vous-même ne sont jamais nettoyés, uniquement ceux installés automatiquement via le tableau dependencies d’un autre plugin. Le même comportement de confirmation s’applique. Lorsque stdin ou stdout n’est pas un terminal, la désinstallation se termine quand même, mais l’étape prune liste les orphelins et ne supprime rien sauf si vous passez -y. Par exemple, pour désinstaller deploy-kit et nettoyer les dépendances qu’il laisse derrière :

​
Résoudre les erreurs de dépendance

Les problèmes de dépendance apparaissent dans claude plugin list et dans l’interface /plugin, sous forme de messages d’erreur descriptifs plutôt que les codes littéraux de ce tableau. Claude Code désactive le plugin affecté jusqu’à ce que vous résolviez l’erreur. Le tableau ci-dessous liste les erreurs les plus courantes et comment les résoudre. Pour vérifier ces erreurs par programmation, exécutez claude plugin list --json. Les plugins avec des problèmes incluent un champ errors les listant. Les plugins qui se sont chargés correctement omettent le champ.

​
Voir aussi