Quarto 1.10.18 sur Mac : que faire si l’export PDF échoue ? Dépannage 2026

« L’export a échoué » décrit plusieurs pannes différentes. Avant de changer une dépendance ou de nettoyer un dossier, précisez ce que vous observez :

• Aucun PDF n’est produit. Le rendu peut s’arrêter au moment de lire le document, d’exécuter une cellule ou d’appeler le moteur PDF.
• La commande se termine avec une erreur. Le texte du terminal indique souvent l’étape concernée, mais la dernière ligne n’est pas toujours la cause initiale. Relevez le premier message d’erreur explicite et les lignes qui le précèdent.
• Le PDF existe, mais son contenu est incomplet ou incorrect. Une référence absente, une police de remplacement ou un graphique manquant peut se produire même si le processus de rendu a fini par produire un fichier.

Ces symptômes impliquent des vérifications différentes. Réinstaller Quarto avant de les distinguer peut modifier le chemin des outils ou supprimer des indices, sans corriger une configuration YAML invalide, une cellule en échec ou un fichier de police absent.

La documentation de dépannage de Quarto recommande de partir de la commande de rendu et des messages produits, puis d’isoler le problème (procédure officielle de dépannage). Conservez donc le journal complet, la commande exacte, une copie de la source et le chemin de travail. Si le projet contient des données de recherche, utilisez une copie expurgée pour les tests que vous partagez.

Avant d’agir, gardez les éléments qui permettront de comparer un rendu défaillant à un rendu réussi. Ne supprimez pas encore les caches, les fichiers temporaires ou le dossier de sortie : ils peuvent aider à comprendre si le document réutilise un résultat ancien.

Cochez les éléments suivants :

• [ ] Copiez la commande exacte utilisée, y compris ses options.
• [ ] Enregistrez toute la sortie du terminal, depuis le début du rendu jusqu’au code de retour ou au message final.
• [ ] Dupliquez le fichier source et les fichiers de configuration du projet, sans modifier l’original.
• [ ] Notez le dossier depuis lequel la commande a été lancée et le chemin du fichier d’entrée.
• [ ] Conservez une copie du PDF, même s’il paraît incomplet, et notez ce qui manque.
• [ ] Relevez les sorties de quarto --version et de quarto check.

La référence de la commande quarto render décrit son rôle et ses options. Pour une première comparaison, une commande explicite du type quarto render rapport.qmd --to pdf permet de rendre visible le fichier source et le format demandé. Remplacez rapport.qmd par le nom réel de votre document. Si le projet possède une configuration partagée, vérifiez aussi si elle sélectionne ou remplace le format de sortie.

Créez ensuite un document provisoire, indépendant des données du projet. Gardez uniquement un titre et un paragraphe, puis tentez le rendu PDF. Si ce document échoue également, concentrez-vous sur l’installation, le moteur ou les dépendances globales. S’il réussit, le problème est probablement lié à une configuration, une extension ou un contenu propre au projet. Ce test ne prouve pas que le rapport scientifique est correct : il sert seulement à réduire le périmètre de la panne.

Un nom de version affiché dans une fenêtre ou un ancien journal ne prouve pas que le terminal appelle le même exécutable. Confirmez la version active avec quarto --version, puis comparez-la à la version que vous pensez utiliser. La page officielle des versions publiées permet de vérifier la présence de Quarto 1.10.18 ; elle ne garantit pas que cette version, à elle seule, soit compatible avec chaque projet, chaque police ou chaque installation de macOS.

Vérifiez ensuite le contexte d’exécution. Depuis le terminal, pwd affiche le dossier courant et command -v quarto indique quel exécutable est trouvé par le chemin de recherche du shell. Comparez ces résultats avec ceux obtenus depuis votre éditeur, si vous lancez le rendu depuis une interface graphique. Un environnement de terminal et une application peuvent utiliser des chemins différents.

Inspectez le document et les fichiers de projet :

• Recherchez une erreur d’indentation ou de syntaxe dans l’en-tête YAML. Une valeur mal placée peut empêcher l’interprétation du format.
• Confirmez que le fichier nommé dans la commande existe dans le dossier courant, ou donnez son chemin correct.
• Examinez les options du format PDF et les références à un modèle, à un filtre ou à une extension.
• Vérifiez si le projet contient un fichier _quarto.yml qui définit des options communes ou plusieurs formats.
• Pour chaque essai, ne changez qu’un seul réglage et notez la différence dans le journal.

La documentation officielle explique la structure des projets Quarto et les options du format PDF. Appuyez-vous sur ces références pour valider la syntaxe au lieu de recopier une configuration trouvée pour un autre projet. Lorsque la source minimale fonctionne, réintroduisez les options de projet progressivement ; arrêtez-vous dès que le défaut réapparaît et conservez cette version comme cas de reproduction.

Une cellule de code peut échouer avant même que Quarto ne demande au moteur PDF de composer le document. Pour séparer les deux étapes, repérez dans le journal si l’erreur survient pendant l’exécution du code ou après le lancement de l’outil de compilation. Un message indiquant un noyau introuvable, un module manquant ou un interpréteur inaccessible oriente vers l’environnement de code ; une erreur de commande LaTeX après l’exécution des cellules oriente vers la chaîne PDF.

Vérifiez que le moteur d’exécution déclaré correspond au contenu du document. Pour R, assurez-vous que l’installation et les paquets nécessaires sont disponibles dans l’environnement réellement appelé. Pour Python, vérifiez l’interpréteur, le noyau et les bibliothèques du projet, plutôt que de supposer que l’environnement activé dans une autre fenêtre est utilisé ici. Une exécution manuelle réussie dans un terminal ne garantit pas que Quarto voit le même chemin ou le même environnement.

Pour isoler le problème, copiez une cellule représentative dans un document d’essai et retirez les données sensibles. Choisissez un exemple qui dépend d’une bibliothèque ou d’une étape pertinente, sans y inclure de fichiers confidentiels. Lancez le rendu avec l’exécution activée, puis, si votre configuration le permet, comparez avec un rendu qui réutilise les résultats de code déjà calculés. Si seul le premier échoue, examinez l’interpréteur et les dépendances. Si les deux échouent au même moment de la compilation, poursuivez plutôt côté PDF.

Les options de cache ou de sortie figée peuvent compliquer le diagnostic : un résultat visible dans le document peut provenir d’un calcul antérieur et ne pas refléter la dernière exécution. Écartez cette ambiguïté sur une copie, en rendant explicitement les cellules nécessaires et en notant les options utilisées. Ne videz pas les caches du projet original avant d’avoir sauvegardé les résultats dont vous pourriez avoir besoin. La validation du rendu établit seulement que le processus s’est exécuté ; elle ne valide ni la méthode, ni les données, ni l’interprétation scientifique.

Commencez par identifier l’étape et l’outil nommés dans le journal, plutôt que d’installer une autre distribution LaTeX immédiatement. Quarto peut employer différents moteurs PDF. Le moteur configuré dans le document ou le projet ne correspond pas nécessairement à celui que vous imaginiez, et le terminal peut trouver un exécutable différent de celui attendu.

Relevez l’option pdf-engine dans le document ou la configuration, puis recherchez le chemin réel de l’outil demandé avec command -v lualatex, command -v xelatex ou le nom mentionné dans l’erreur. Si la commande ne retourne aucun chemin, l’exécutable n’est pas accessible depuis ce shell. Si elle retourne un chemin, ce résultat identifie l’exécutable trouvé, mais ne prouve pas que ses paquets ou ses polices soient complets.

La documentation Quarto sur les moteurs PDF et TinyTeX présente le choix de moteur et les pistes liées à l’installation TeX. Comparez le journal obtenu avec la distribution TeX déjà installée à celui obtenu avec TinyTeX si vous envisagez cette dernière. Ne modifiez pas simultanément le moteur, la distribution et les réglages du document : vous ne sauriez plus quel changement a corrigé ou aggravé le problème.

Pour un paquet manquant, relevez son nom exact dans le journal et vérifiez quelle distribution est appelée avant de lancer une installation. Si un mécanisme d’installation automatique échoue, le problème peut concerner l’accès au réseau, les droits d’écriture ou le chemin de la distribution, pas nécessairement le document Quarto. En environnement administré, demandez avant toute modification si les paquets TeX doivent être installés par l’équipe informatique.

Comment confirmer le chemin du moteur PDF réellement utilisé ?

Inspectez l’option de moteur dans la configuration, puis comparez-la au chemin indiqué par la sortie du terminal et par le journal de rendu. Vous pouvez aussi lancer une vérification indépendante de l’exécutable attendu avec command -v lualatex, en remplaçant son nom par celui signalé dans le document. Si plusieurs installations sont accessibles, conservez les chemins et les journaux avant de changer le PATH ou le moteur.

Arrêtez les essais si vous ne pouvez plus déterminer quelle installation est appelée, ou si une modification globale affecte d’autres projets. Revenez alors à la copie de travail et demandez une vérification de l’environnement au support informatique. Une compilation réussie après modification ne suffit pas à établir qu’elle utilise la même chaîne que celle de vos collègues ou de votre environnement de remise.

Un PDF produit peut encore être inutilisable pour la remise si les caractères, les figures ou les références ne sont pas rendus comme prévu. Ne traitez pas ces défauts comme un seul problème LaTeX : chaque type de contenu dépend de réglages et de fichiers différents.

Police absente ou caractères manquants

Si des caractères sont remplacés, apparaissent sous forme de carrés ou disparaissent, relevez d’abord le moteur PDF configuré et le nom exact de la police demandée. Vérifiez ensuite que cette police est réellement accessible dans l’environnement qui effectue le rendu et qu’elle couvre les caractères employés dans le document. Une police portant un nom proche ne garantit pas la présence des glyphes nécessaires.

La configuration qui fonctionne sur votre Mac local peut échouer sur une autre machine, car la police ou son chemin peut manquer. Reproduisez le test avec une courte chaîne représentative, notamment les caractères problématiques, dans le document minimal. Si le défaut concerne uniquement certains caractères, conservez le moteur et la configuration stables pendant que vous testez la police ; si l’ensemble du rendu échoue, revenez au diagnostic du moteur.

Figures absentes ou mal placées

Pour une figure manquante, vérifiez le chemin du fichier par rapport au dossier d’exécution, son nom exact et le format réellement produit par le code. Une image créée dans un dossier temporaire ou relatif peut ne pas exister lorsque Quarto lance le rendu depuis le dossier du projet. Confirmez également que l’étape de génération de la figure a été exécutée, plutôt que de supposer que le fichier est récent.

Sur une copie, testez une figure isolée avec un chemin simple et vérifiez le résultat dans le PDF. Si elle apparaît, réintroduisez ensuite les figures du rapport une par une ; si elle ne s’affiche pas, comparez le journal de génération du graphique au message du moteur PDF. Cette séparation est particulièrement utile pour les rapports comportant des visualisations, des planches d’images ou des éléments issus d’un travail audio ou vidéo.

Références non actualisées et renvois incohérents

Pour une bibliographie vide ou un renvoi incorrect, contrôlez le chemin du fichier bibliographique et les clés citées dans le document. La référence de Quarto sur les citations et bibliographies décrit la configuration à vérifier. Relevez dans le journal les erreurs associées au traitement des références ou aux étapes de compilation supplémentaires ; ne concluez pas à un défaut de police parce qu’une citation manque.

Contrôlez enfin le PDF livré lui-même. Vérifiez des références choisies, les renvois internes, les numéros de page, les figures et les caractères sensibles. Si la version remise est déterminée par une convention de laboratoire ou de revue, cette vérification doit suivre leurs exigences : un rendu techniquement réussi ne vaut pas validation éditoriale.

Utilisez ces conditions pour choisir une action à faible risque :

• Si le document minimal échoue avant toute exécution de code, vérifiez le binaire Quarto actif, le dossier de travail, le moteur et la distribution TeX. Ne modifiez pas le contenu scientifique tant que le rendu de base est en panne.
• Si le document minimal fonctionne et que le projet échoue, restaurez les options du projet sur une copie, puis réintroduisez le contenu par catégories : configuration, code, figures, références et modèle. Revenez au dernier état fonctionnel dès qu’un ajout reproduit l’erreur.
• Si les cellules échouent avant la compilation PDF, contrôlez l’interpréteur, le noyau et les dépendances déclarées. Ne changez pas de moteur PDF pour corriger une erreur produite pendant l’exécution du code.
• Si le PDF est généré mais que des éléments manquent, testez séparément polices, figures et références, puis faites valider le résultat selon les exigences de remise du projet.
• Si le défaut ne se reproduit plus ou si plusieurs outils sont appelés de manière incohérente, cessez les modifications de l’installation globale. Préparez une copie expurgée et demandez une vérification dans un environnement contrôlé.

Cette progression permet de conserver un chemin de retour. Après chaque changement, relancez la même commande sur le même fichier de test et comparez les journaux. Si vous changez à la fois de moteur, de paquet et de configuration, vous perdez la possibilité d’attribuer le résultat à une cause précise.

Lorsque le document minimal fonctionne, vérifiez votre copie de projet par étapes. Restaurez d’abord le fichier de configuration, puis le moteur et le modèle, ensuite les cellules de code, les figures et la bibliographie. Cette remise en place par familles de dépendances indique quel composant fait réapparaître la panne et fournit un cas reproductible à transmettre au support.

Avant la livraison, cochez les contrôles pertinents :

• [ ] La commande de rendu, le chemin du document et les options de sortie sont consignés.
• [ ] La version de Quarto et le moteur PDF effectivement appelés sont identifiés.
• [ ] Les cellules attendues ont été exécutées dans l’environnement prévu ; aucun résultat ancien n’est pris pour un résultat récent.
• [ ] Les figures sont présentes et lisibles dans le PDF final.
• [ ] Les polices et les caractères nécessaires sont rendus correctement dans l’environnement de validation.
• [ ] Les citations, la bibliographie et les renvois ont été vérifiés dans le fichier produit.
• [ ] Le résultat a été confronté aux exigences scientifiques et éditoriales du projet.

Ne transmettez pas un projet complet à un environnement extérieur avant d’avoir vérifié les règles de confidentialité, les autorisations institutionnelles et la présence éventuelle de données personnelles ou sensibles. Une copie expurgée doit retirer les éléments confidentiels tout en conservant assez de structure pour reproduire le défaut. Si vous ne pouvez pas produire cette copie, demandez d’abord conseil au responsable des données ou au support de votre établissement.

Quand le Mac local a une installation instable, les réinstallations successives peuvent rendre les différences de chemins et de paquets plus difficiles à expliquer. Un serveur Linux ou un environnement d’un autre système ne reproduit pas forcément le comportement de macOS. À l’inverse, si vous rendez régulièrement des projets lourds ou devez accéder à des périphériques physiques, une machine institutionnelle ou un Mac dédié peut être plus adapté qu’un accès distant ponctuel.

Pour une vérification limitée, CALMVPS peut constituer une option d’environnement macOS distant : vous pouvez comparer le rendu d’une copie expurgée sans remplacer immédiatement votre poste de travail. Avant de choisir, évaluez le transfert de fichiers, les règles de données de votre laboratoire et la possibilité de contrôler les mêmes dépendances. Consultez les tarifs des offres CALMVPS seulement si cette validation répond à un besoin réel ; si votre équipe a besoin d’un accès macOS pour des rendus réguliers, examinez aussi les solutions Mac à distance. Dans tous les cas, conservez le journal, le résultat PDF et la commande reproductible : l’accès à un autre environnement n’est utile que si vous pouvez comparer les mêmes entrées, et un rendu réussi ne certifie pas à lui seul la validité des résultats de recherche.