Votre application démarre sur votre poste, mais le Mac de votre collègue ne trouve ni les données ni certaines bibliothèques ? La solution la plus contrôlable consiste à construire avec PyInstaller dans macOS, à valider d’abord le mode dossier, puis à choisir le mode fichier unique seulement si le besoin de livraison le justifie.

Cet article s’adresse aux étudiants et doctorants qui transmettent leurs scripts d’analyse à des collègues sur Mac. Il est aussi destiné aux développeurs scientifiques qui empaquettent une interface graphique, des fichiers de données ou des bibliothèques natives, ainsi qu’aux équipes techniques universitaires qui doivent définir une procédure reproductible.

Avant la construction : fixer la cible et le niveau de livraison

PyInstaller ne transforme pas un paquet construit sur Windows en application Mac. Pour produire une application destinée à macOS, vous devez effectuer la construction dans un environnement macOS ; la documentation de PyInstaller précise que les paquets sont propres au système sur lequel l’outil est exécuté et qu’il faut construire séparément pour chaque système cible. Vérifiez cette règle dans les instructions officielles sur les plateformes et la construction.

PyInstaller peut-il créer directement une application Mac depuis Windows ? Non : partez d’un Mac accessible localement ou à distance et réalisez-y la construction. Une archive copiée depuis Windows n’est pas un substitut à une compilation sur macOS. Les besoins de compatibilité liés à l’architecture du Mac cible doivent également être vérifiés sur les machines que l’application devra réellement prendre en charge ; ne déduisez pas cette compatibilité du seul fait que la construction s’est terminée sans erreur.

Avant de préparer l’environnement, définissez le résultat attendu. Ces objectifs n’ont pas les mêmes critères d’acceptation :

  • Validation interne au laboratoire : l’application démarre dans un environnement contrôlé et exécute un cas d’analyse représentatif.
  • Transmission à un collaborateur : le destinataire peut ouvrir l’application, choisir ses données, retrouver les résultats et comprendre les éventuelles limites d’utilisation.
  • Distribution à des utilisateurs externes : en plus du fonctionnement, vous devez examiner les exigences de signature, de notarisation et de distribution applicables à votre mode de diffusion.
Un lancement réussi ne prouve donc ni la justesse scientifique des résultats ni la préparation à une diffusion publique. Gardez ces critères séparés pendant toute la procédure. Une application qui s’ouvre peut encore échouer au moment de lire un fichier de référence, d’enregistrer une sortie ou de fonctionner sous un autre compte. De même, une analyse correcte sur votre poste ne signifie pas automatiquement que l’application est présentée et distribuée selon les exigences destinées aux utilisateurs externes.

Préparer une copie reproductible du projet

Ne lancez pas PyInstaller directement sur la seule copie du projet qui sert aux analyses. Créez une copie de travail que vous pourrez reconstruire ou abandonner, puis conservez la source originale et les résultats de référence hors de cette copie. Cette séparation permet de déterminer si un défaut vient de l’empaquetage, d’une modification du code ou de la logique d’analyse.

Dans cette copie, relevez les informations nécessaires à une reconstruction : version de Python, version de PyInstaller, dépendances installées, architecture visée et commandes utilisées. La documentation officielle des changements de PyInstaller identifie la version 6.22.3 ; vous pouvez épingler cette version dans votre environnement pour éviter qu’une reconstruction ultérieure installe silencieusement une autre version (historique officiel des versions de PyInstaller). Cela ne remplace pas la consignation des autres dépendances du projet.

Préparez ensuite un inventaire des éléments qui ne sont pas du code Python. Pour un outil scientifique, il peut s’agir de fichiers de configuration, de modèles, de tables de référence, de ressources d’interface et d’échantillons d’entrée. Pour une application d’analyse audio ou vidéo, vérifiez aussi les formats de fichiers attendus et les ressources utilisées par les fonctions d’importation ou d’exportation. Un fichier présent dans le dépôt n’est pas nécessairement incorporé automatiquement dans le paquet.

Examinez enfin les règles d’accès aux données avant de lancer les essais. Utilisez des échantillons non sensibles et confirmez que les autorisations du laboratoire permettent leur copie dans un environnement de construction. N’intégrez pas par inadvertance des données nominatives, des clés d’accès, des chemins privés ou des données de recherche dont la diffusion n’est pas autorisée. Si les données ne peuvent pas être copiées vers la machine de construction, identifiez dès cette étape un jeu d’essai de substitution autorisé ou demandez au responsable du projet de définir une procédure conforme.

Un paquet de test doit contenir assez d’éléments pour reproduire le parcours réel, mais pas les données confidentielles du projet. Si vous ne pouvez pas remplacer un jeu de données sensible par un échantillon autorisé, arrêtez la validation et faites définir une procédure par le responsable du projet.

Construire en mode dossier et examiner les dépendances

Dans l’environnement macOS préparé pour le projet, créez un environnement Python isolé et installez les dépendances nécessaires à l’application. Installez ensuite la version de PyInstaller retenue. La commande suivante illustre une installation épinglée ; adaptez le nom du module d’entrée à votre projet.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install PyInstaller==6.22.3
python -m pip install -r requirements.txt

La commande d’installation épingle la version du constructeur ; elle ne garantit pas, à elle seule, que les dépendances de recherche soient figées. Conservez donc aussi le fichier de dépendances réellement utilisé et les informations de l’environnement. Pour les options de construction, les modes disponibles et leur syntaxe, consultez la référence officielle de la ligne de commande PyInstaller.

Commencez par un paquet en mode dossier, souvent appelé onedir. Il sépare l’exécutable et les éléments requis dans une structure que vous pouvez examiner. Par exemple :

python -m PyInstaller --onedir --windowed --name Analyse main.py

Remplacez main.py par le point d’entrée de votre projet. Si votre application est un outil en ligne de commande plutôt qu’une interface graphique, ne reprenez pas automatiquement l’option --windowed : choisissez les options correspondant au comportement attendu. Les options et leurs effets sont décrits dans la documentation de PyInstaller sur l’utilisation de l’outil.

Après la construction, vérifiez le contenu du dossier produit. Confirmez que les modules importés, les bibliothèques natives nécessaires et les fichiers de données attendus sont présents. Si le programme importe un module de façon dynamique, l’analyse automatique peut ne pas le détecter ; consignez l’erreur, identifiez l’import manquant, puis corrigez la configuration du projet. PyInstaller permet de traiter ces besoins au moyen de fichiers de spécification et de hooks : consultez ses explications sur les fichiers de données et les fichiers de spécification ainsi que sur le mécanisme des hooks.

Que faire si les fichiers de données du projet sont introuvables après l’empaquetage ? Déterminez d’abord si le fichier est absent du paquet ou si le programme le cherche dans le mauvais répertoire. Comparez le contenu produit avec l’inventaire établi avant la construction. Ajoutez ensuite explicitement les ressources nécessaires dans la configuration de PyInstaller, puis reconstruisez et répétez le même test. La documentation sur les fichiers de spécification décrit la déclaration des données à inclure ; adaptez-la à la structure de votre application plutôt que de copier une configuration générique.

Le code ne doit pas non plus supposer que le répertoire de lancement est toujours celui du projet d’origine. Testez le comportement lorsque l’application est lancée depuis le Finder, et non uniquement depuis le terminal ouvert à la racine du dépôt. Distinguez les ressources qui doivent être lues par l’application des résultats que l’utilisateur doit pouvoir créer et modifier : les fichiers de sortie doivent aller vers un emplacement prévu pour l’écriture, par exemple un dossier choisi par l’utilisateur, et non vers une ressource incorporée au paquet.

Pour chaque défaut constaté, consignez le fichier recherché, le chemin effectivement utilisé et l’étape exacte qui échoue. Une correction est plus facile à vérifier si vous pouvez la relier à un symptôme reproductible, plutôt que de modifier plusieurs chemins ou paramètres à la fois. Une fois le fichier ou le module manquant ajouté, relancez la construction depuis la copie de travail propre ; évitez de ne tester que l’application déjà produite, car elle ne permettrait pas de confirmer que la correction est reproductible.

Tester l’interface et comparer les résultats scientifiques

Une fois le mode dossier construit, lancez l’application depuis le Finder. Cette vérification révèle des écarts que l’exécution depuis un terminal peut masquer : dialogue de sélection de fichiers absent, fenêtre qui ne s’ouvre pas, dépendance introuvable ou message d’erreur invisible dans une interface graphique.

Effectuez ensuite un parcours d’essai documenté :

  • Ouvrez l’application depuis le Finder et vérifiez que l’interface attendue apparaît.
  • Essayez les interactions principales : sélection d’un fichier, modification des paramètres et déclenchement de l’analyse.
  • Utilisez un échantillon d’entrée connu et conservez la sortie de référence obtenue avec le projet Python non empaqueté.
  • Comparez les résultats selon des critères scientifiques définis par le projet, sans assimiler une différence d’affichage à une différence de calcul.
  • Enregistrez le résultat dans l’emplacement prévu, puis vérifiez que le fichier existe, qu’il peut être rouvert et qu’il n’a pas été écrit dans un emplacement temporaire.
  • Conservez les messages d’erreur et les journaux utiles à la reproduction du problème.
Le test doit permettre d’isoler deux catégories de défauts. Un fichier absent, un import non collecté ou un chemin incorrect relève de la construction ou de l’exécution du paquet. Une formule erronée, un résultat incohérent déjà présent dans la version Python ou un traitement de données inattendu relève plutôt du programme ou de sa méthode scientifique. Si vous mélangez ces diagnostics, vous risquez de modifier la logique d’analyse pour compenser un défaut de packaging.

Pour une application de traitement audio ou vidéo, incluez dans l’essai les formats réellement utilisés et vérifiez que l’enregistrement conserve les caractéristiques attendues par votre protocole. Pour un outil de visualisation scientifique, validez aussi l’ouverture des fichiers représentatifs et l’exportation des figures. Ces contrôles sont plus utiles qu’un simple écran d’accueil : ils confirment qu’un utilisateur peut accomplir une tâche de recherche de bout en bout.

Choisir le mode de livraison avec une liste de décision

Cochez la condition qui correspond à votre situation, puis appliquez la décision indiquée. Si plusieurs conditions s’appliquent, retenez d’abord celle qui impose le contrôle le plus strict ; en cas d’échec, revenez au mode dossier.

  • [ ] Le paquet présente encore un défaut de dépendance, de ressource ou de chemin. Gardez onedir. Inspectez les éléments produits, corrigez le défaut et reconstruisez avant de tester un autre mode.
  • [ ] Le laboratoire ou le collaborateur peut recevoir un dossier, et les essais en mode dossier sont réussis. Livrez onedir, en joignant la procédure de lancement, les versions utilisées et les limites connues.
  • [ ] Le destinataire exige un fichier unique pour une raison précise, et le mode dossier a passé les essais. Essayez onefile dans une construction distincte, puis répétez le parcours d’essai complet : ouverture depuis le Finder, lecture des données, analyse de référence et sauvegarde des résultats.
  • [ ] L’application est destinée à des utilisateurs externes. Traitez la signature, la notarisation et les exigences du canal de distribution comme une étape indépendante ; ni onedir ni onefile ne prouve à lui seul que la distribution est prête.
  • [ ] Une reconstruction ne reproduit pas les résultats attendus ou une vérification échoue. Ne passez pas à la livraison : revenez à la dernière construction en mode dossier qui fonctionnait et consignez l’écart.
Le mode onedir est un meilleur point de départ lorsque vous devez inspecter les dépendances, diagnostiquer un fichier manquant ou transmettre une application à une équipe qui accepte un dossier d’installation. Le mode onefile regroupe la livraison sous la forme d’un fichier unique, mais ne simplifie pas le diagnostic : il modifie le mode de chargement des éléments au démarrage et doit faire l’objet de nouveaux essais. PyInstaller documente ces deux modes et leurs comportements dans sa [présentation des modes de fonctionnement](https://pyinstaller.org/en/stable/operating-mode.html).

Comment choisir entre onedir et onefile ? Gardez onedir tant que vous devez examiner les bibliothèques, les ressources ou les erreurs d’importation, ou si votre équipe accepte un dossier d’installation. Passez à onefile seulement si la remise d’un fichier unique répond à une contrainte concrète et si le mode dossier a réussi les tests. Après ce changement, rejouez le parcours complet : lancement depuis le Finder, ouverture des données, analyse de référence, sauvegarde des résultats et vérification des journaux. Ne réutilisez pas les preuves recueillies pour onedir comme preuve de bon fonctionnement de onefile.

Distinguer validation, reproductibilité et distribution

Une acceptation correcte comporte plusieurs niveaux. Le premier confirme que l’application démarre. Le suivant vérifie qu’un autre lancement, dans une copie distincte du projet ou sous un autre compte Mac, permet de retrouver les données nécessaires et d’obtenir les résultats attendus. Le dernier porte sur les conditions de distribution à des utilisateurs externes ; il ne se déduit pas des deux premiers.

Une application PyInstaller pour Mac doit-elle être signée et notarisée ? Cela dépend du canal de distribution et des exigences applicables à votre cas. Ne cherchez pas à contourner les contrôles de sécurité pour faire démarrer un paquet : vérifiez les règles en vigueur dans la documentation officielle d’Apple sur la distribution des logiciels macOS. La signature, la notarisation et la diffusion sont des questions distinctes de la collecte des dépendances par PyInstaller.

Avant la remise, réunissez les éléments qui permettront au destinataire de comprendre ce qu’il reçoit : système et architecture visés, versions de construction, dépendances consignées, échantillon de validation autorisé, commande ou fichier de configuration utilisé, résultat attendu et limites connues. Faites refaire le test par une personne qui n’a pas construit le paquet. Si elle a besoin de votre dépôt complet, de vos variables d’environnement ou de chemins personnels pour lancer l’application, la procédure de livraison n’est pas encore suffisamment reproductible.

Pour décider où construire, demandez-vous si vous disposez déjà d’un Mac conforme à la cible et si les règles du laboratoire autorisent les données de test sur cette machine. Si votre équipe ne possède pas de Mac adapté, comparez les besoins du projet avec les environnements Mac présentés par MACGPU et examinez les conditions d’accès avant de transférer du code ou des données. Une machine distante ne dispense pas de contrôler les autorisations, les échantillons utilisés ni les exigences de conservation des fichiers.

L’achat d’un Mac peut être pertinent si vous avez besoin d’un poste durable, d’un accès physique aux périphériques ou de travaux réguliers qui justifient une machine dédiée. À l’inverse, construire uniquement depuis Windows laisse sans réponse le besoin d’un environnement macOS ; maintenir une machine personnelle uniquement pour une validation ponctuelle immobilise du matériel ; et remettre un paquet sans test sur un autre Mac expose l’équipe aux fichiers manquants, aux résultats non vérifiés et aux erreurs de chemin. Pour un besoin temporaire de construction ou de recette, une location de Mac auprès de MACGPU peut donc éviter d’acheter un poste dédié, à condition que le mode d’accès et les règles de données du laboratoire conviennent à votre projet. Vous pouvez comparer les options d’accès Mac de MACGPU avant de décider.