Commencez par identifier le compte qui exécute la commande, le shell réellement lancé et le préfixe d’installation de Homebrew ; vérifiez ensuite si ce shell charge brew shellenv. Si le terminal interactif fonctionne mais que SSH, la CI ou une tâche en arrière-plan échoue, corrigez l’environnement concerné au lieu de réinstaller Homebrew ou de modifier les permissions à l’aveugle.

Cet article s’adresse aux développeurs qui utilisent Homebrew par SSH sur un Mac distant.
Il concerne aussi les ingénieurs qui maintiennent une CI macOS ou des tâches planifiées, ainsi que les responsables d’une machine partagée qui doivent vérifier le compte et la configuration du shell.

Maintenant : recueillez le compte, le shell, le chemin de brew et l’erreur complète dans le contexte qui échoue.
Cette semaine : reproduisez la commande dans la tâche réelle, puis consignez les éléments de diagnostic avec son journal d’exécution.

01

Distinguer une commande brew introuvable d’un outil absent

« Homebrew introuvable sur un Mac distant » peut désigner plusieurs pannes. Le shell peut ne pas trouver brew lui-même. À l’inverse, brew peut fonctionner tandis qu’un logiciel installé par Homebrew — par exemple git, node ou un outil de compilation — reste absent du PATH. Enfin, les commandes peuvent réussir dans une session interactive et échouer uniquement dans un Runner ou une tâche planifiée.

Cette distinction évite un faux diagnostic coûteux. Réinstaller un paquet ne corrige pas un PATH incomplet. Réinstaller Homebrew ne garantit pas que le processus CI utilisera le même compte ou le même shell que votre terminal. Et modifier les droits de tout un répertoire peut créer un problème de sécurité sans rendre la commande visible.

Avant de toucher à la configuration, notez les éléments suivants dans le contexte où l’échec se produit :

  • la commande complète et son message d’erreur, sans supprimer les lignes précédentes du journal ;
  • le compte réellement utilisé, obtenu avec id ou whoami ;
  • le shell du processus, vérifié avec ps -p $$ -o comm= ; $SHELL indique le shell de connexion configuré, mais ne prouve pas à lui seul quel interpréteur exécute la commande courante ;
  • le résultat de command -v brew et, si brew est accessible, de brew --prefix ;
  • le mode d’accès : terminal local, session SSH interactive, commande SSH non interactive, Runner CI, service ou tâche planifiée.

Pourquoi SSH peut-il ne pas trouver brew alors qu’une session locale le trouve ? Parce que les deux contextes ne lancent pas nécessairement le même shell et ne lisent pas forcément les mêmes fichiers d’initialisation. Il faut donc comparer les environnements réellement exécutés, plutôt que supposer que toute connexion SSH hérite du PATH du terminal graphique.

Pour un test initial, exécutez ces commandes dans le contexte défaillant et conservez leur sortie :

id
ps -p $$ -o comm=
printf '%s\n' "$PATH"
command -v brew

Si command -v brew ne renvoie aucun chemin, poursuivez avec le contrôle du préfixe et des fichiers de démarrage. Si brew est trouvé mais que c’est un outil géré par Homebrew qui échoue, examinez plutôt le PATH de cet outil et la commande exacte utilisée par le script.

02

Vérifier le préfixe au lieu de deviner le chemin

La documentation Homebrew distingue les préfixes par défaut associés aux architectures : /opt/homebrew pour Apple Silicon et /usr/local pour Intel. Ce sont des valeurs par défaut documentées, pas une preuve de l’emplacement de votre installation. Une migration, une configuration personnalisée ou une ancienne installation peut produire une situation différente ; vérifiez donc la machine concernée avant de modifier un fichier. Consultez les préfixes par défaut décrits dans la FAQ Homebrew et les instructions officielles d’installation.

Lancez d’abord les contrôles depuis un shell où brew fonctionne, si vous en avez un :

brew --prefix
brew config
brew doctor

La page de référence de la commande brew et de ses diagnostics décrit ces commandes. Elles permettent de confronter le chemin renvoyé par Homebrew à l’architecture de la machine et aux informations disponibles sur l’installation. Ne recopiez pas le chemin d’un exemple dans un fichier de configuration avant d’avoir établi que ce chemin correspond à votre hôte.

Observation Interprétation à tester Contrôle suivant
command -v brew ne renvoie rien Le binaire peut être absent du PATH de ce shell Confirmer le préfixe depuis une session fonctionnelle, puis vérifier le fichier de démarrage approprié
brew fonctionne, mais pas un paquet Le problème peut concerner le PATH de l’outil ou son installation Vérifier command -v nom-de-l-outil et sa formule dans le contexte défaillant
Le terminal fonctionne, mais pas le Runner Le compte, le shell ou les variables d’environnement diffèrent Afficher ces valeurs dans les journaux de la tâche
Le chemin existe, mais l’exécution échoue Les droits ou le propriétaire du préfixe peuvent être incohérents Examiner les permissions avant toute correction

La sortie de brew --prefix n’est utile que si la commande est accessible dans ce contexte. Si elle ne l’est pas, ne concluez pas que Homebrew est absent : essayez de retrouver l’installation depuis une session connue comme fonctionnelle, puis comparez son compte et son shell à ceux du processus fautif.

03

Corriger l’initialisation du shell utilisé par SSH

Sur un Mac, le shell configuré pour votre compte et celui d’une commande distante ne sont pas nécessairement lancés dans les mêmes conditions. Avec zsh, les fichiers lus varient selon que la session est interactive ou de connexion. La documentation officielle des fichiers de démarrage de zsh détaille ces différences ; évitez donc de déplacer des réglages entre .zprofile, .zshrc et les autres fichiers sans vérifier le type de shell invoqué.

La commande suivante affiche la configuration d’environnement que Homebrew recommande pour le shell courant :

brew shellenv

Examinez sa sortie avant de l’ajouter à un fichier. Le principe est de faire charger cette configuration dans le fichier effectivement lu par le processus concerné, pas de la copier indifféremment dans plusieurs fichiers. La documentation de la commande brew shellenv explique son rôle dans la configuration de l’environnement.

Pour isoler le problème, comparez d’abord ces deux exécutions :

ssh utilisateur@hote 'printf "%s\n" "$PATH"; command -v brew'

Puis ouvrez une session SSH interactive et exécutez les mêmes vérifications. Si la commande fonctionne dans la session interactive mais pas avec la commande distante entre apostrophes, la différence concerne probablement le mode d’initialisation ou l’environnement fourni au processus. Si aucune des deux ne trouve brew, vérifiez aussi le compte et le préfixe avant de toucher aux fichiers du shell.

Ne supposez pas non plus que .zshrc est systématiquement lu par un processus automatisé. Un script peut lancer un autre interpréteur, ou le Runner peut démarrer un shell non interactif. Pour les scripts, une option robuste consiste à définir explicitement le PATH nécessaire dans le contexte du travail, après avoir confirmé le préfixe réel. Une autre consiste à charger l’initialisation documentée par Homebrew depuis le shell et le fichier adaptés. Dans les deux cas, la validation doit porter sur la commande exécutée par SSH, pas uniquement sur le terminal que vous utilisez pour administrer la machine.

04

Retrouver le compte et le shell d’une tâche CI ou planifiée

Un Runner, un agent de compilation ou une tâche de fond peut fonctionner sous un compte distinct de celui de l’administrateur. Il peut également démarrer sans les mêmes variables d’environnement qu’une session utilisateur. Une compilation Xcode peut alors réussir dans le terminal tout en échouant au moment de lancer un outil Homebrew dans la CI. Une tâche de traitement audio ou vidéo peut présenter le même symptôme si elle invoque un utilitaire externe depuis un script démarré en arrière-plan.

Ajoutez temporairement au début de la tâche un diagnostic ciblé :

id
ps -p $$ -o comm=
printf 'PATH=%s\n' "$PATH"
command -v brew
brew --prefix

Si la dernière commande échoue, conservez cette erreur : elle apporte une information sur le contexte réel au lieu de masquer le problème. Une tâche ne doit pas être considérée comme réparée parce que l’administrateur peut exécuter brew depuis son propre terminal. Consultez aussi le guide GitHub consacré à la surveillance et au dépannage des exécuteurs autohébergés si votre panne concerne un Runner GitHub Actions.

Comment établir quel shell et quel compte exécute une tâche automatique ? Inscrivez id et ps -p $$ -o comm= dans la sortie de la tâche elle-même, puis comparez-les à une session SSH ouverte avec le compte attendu. Pour connaître le shell configuré sans le confondre avec le processus actif, examinez également les informations du compte ; pour le shell qui exécute réellement le script, privilégiez l’observation dans le processus.

Une fois le contexte confirmé, corrigez le bon niveau :

  • si la tâche utilise un compte différent, fournissez à ce compte une configuration d’environnement adaptée plutôt que de réparer le profil d’un autre utilisateur ;
  • si elle lance un shell différent, chargez l’environnement depuis le fichier ou le script correspondant à ce shell ;
  • si seul le Runner présente le problème, inspectez la configuration de lancement du Runner et son environnement ;
  • si une tâche planifiée ne lit pas les fichiers de démarrage attendus, définissez explicitement les variables requises dans son propre lancement.

La documentation Homebrew destinée aux administrateurs Mac précise les principes de gestion des comptes et des permissions. Elle est particulièrement pertinente sur une machine partagée : la correction doit respecter le modèle de comptes prévu pour l’installation, plutôt que donner à chaque processus des droits administrateur par commodité.

05

Examiner les permissions sans élargir les droits

Si brew existe au chemin attendu mais ne peut pas être lu ou exécuté, collectez des éléments avant toute modification. Vérifiez le compte courant, le propriétaire du préfixe et les permissions des répertoires concernés. Vous pouvez afficher ces informations avec ls -ld sur le préfixe et les chemins parents pertinents, sans changer leur propriétaire au préalable.

Une installation gérée dans un contexte multiutilisateur peut échouer si la tâche s’exécute sous un compte non prévu. À l’inverse, une erreur d’accès à un répertoire précis ne justifie pas de rendre toute l’arborescence accessible en écriture à tous. Les recommandations de Homebrew pour les administrateurs exposent les limites liées au compte qui gère l’installation ; appuyez-vous sur ces règles plutôt que d’improviser une politique de droits.

Évitez sudo brew, les changements récursifs de propriétaire et la réinstallation répétée comme premières tentatives. Ces gestes peuvent brouiller les indices, créer des fichiers appartenant à des comptes inattendus ou étendre les droits sans corriger le PATH. La documentation des problèmes courants Homebrew aide à distinguer les erreurs d’installation des erreurs d’environnement.

Après l’inspection, choisissez la correction la plus limitée. Si le préfixe appartient au compte prévu et que seul le shell de la tâche ne le charge pas, corrigez l’environnement. Si les propriétaires ou les droits ne correspondent pas au modèle prévu, déterminez d’abord comment cette incohérence est apparue. Ne réattribuez pas l’ensemble du préfixe à un utilisateur au hasard : sur un nœud partagé, cette décision peut casser l’usage d’autres tâches.

06

Fermer le diagnostic par une validation reproductible

Une réparation est vérifiée uniquement lorsque la commande représentative fonctionne depuis le contexte qui échouait. Utilisez cette liste au moment de valider le changement :

  • [ ] Le compte observé dans le journal est celui attendu pour SSH, le Runner ou la tâche planifiée.
  • [ ] Le shell constaté dans le processus correspond à celui dont vous avez corrigé l’initialisation.
  • [ ] Le préfixe est confirmé sur cet hôte par Homebrew ou par une session fonctionnelle, et non recopié depuis un exemple.
  • [ ] command -v brew renvoie le chemin attendu dans le contexte défaillant.
  • [ ] command -v retrouve aussi l’outil installé dont le travail a réellement besoin.
  • [ ] La commande représentative s’exécute dans SSH, puis dans la tâche CI ou en arrière-plan concernée.
  • [ ] Le journal conserve le chemin, le compte, le shell, le résultat et le code de sortie utiles au prochain incident.

Si le problème n’apparaît que dans une tâche, réparez d’abord cette tâche ou le lancement du Runner. Si plusieurs comptes rencontrent des incohérences, si le préfixe ne correspond plus à la configuration attendue ou si l’état de l’installation n’est pas fiable, évaluez la remise à niveau du nœud ou son remplacement plutôt que d’empiler des corrections locales.

Pour documenter une configuration réutilisable, gardez séparés le compte, le shell et les outils requis. Cette précaution facilite la reproduction d’un environnement de développement distant et évite de confondre la configuration personnelle d’un administrateur avec celle d’un exécuteur CI. Si votre équipe doit aussi disposer d’un Mac distant pour reproduire les tâches et vérifier la configuration, consultez les options de commande d’un Mac mini distant.

Quand votre solution actuelle consiste à bricoler un serveur Linux, elle ne fournit pas à elle seule les outils macOS requis par une chaîne Apple. S’appuyer uniquement sur un Mac personnel expose aussi les tâches à la disponibilité de cette machine et à sa configuration individuelle ; acheter une machine dédiée ajoute l’achat et la maintenance d’un équipement qui peut rester sous-utilisé entre deux campagnes. Pour un besoin temporaire de reproduction, de compilation ou de validation, louer un Mac auprès de VpsMesh permet de disposer d’un environnement macOS distant sans transformer un achat matériel en préalable. Si votre équipe n’a pas de Mac stable pour isoler ce type de panne, examinez les tarifs de location de Mac mini après avoir défini le compte, le shell et les outils que le nœud doit exécuter.