Qu’est-ce qu’un fichier TOML ?

TOML est un format texte que n’importe quel éditeur ouvre. Il est utilisé pour la retouche.

L’extension est .toml et le nom complet Tom's Obvious Minimal Language. L’un et l’autre comptent moins que ce que le fichier peut contenir, et c’est le sujet du reste de cette page.

Il remonte à 2013. La spécification est TOML 1.0.

L’âge est utile à connaître pour une raison pratique : plus un format est ancien, plus les programmes ont eu le temps de l’apprendre.

Elle est publiée intégralement : n’importe qui peut l’implémenter à partir du document plutôt qu’en l’observant, et c’est pourquoi ce format apparaît dans tant de programmes et pourquoi des fichiers écrits il y a vingt ans s’ouvrent encore. Une spécification publiée n’est pas pour autant libre de redevances : quand un format enveloppe un codec, les brevets sont une question à part, que la norme ne tranche pas.

TOML enregistre son contenu à l’identique. Le réenregistrer ne change rien : vous pouvez l’ouvrir, le modifier et le réenregistrer autant de fois que vous voulez sans accumuler de dégâts, et c’est ce qui en fait un format de travail plutôt qu’un format de livraison.

TOML a une syntaxe de commentaires, et c’est la différence entre un fichier qu’une personne entretient et un fichier qu’un programme écrit. Les commentaires sont la première chose perdue en convertissant vers un format qui n’en a pas, et rien ne vous prévient.

Visual Studio Code le lit, comme la plupart des programmes du même genre.

Quand un fichier ne s’ouvre pas, le format est rarement en cause : le plus souvent, c’est le programme qui est plus ancien que lui. Convertir vers quelque chose de plus ancien est le contournement fiable, et c’est à cela que sert le reste de ce site.

Aucun navigateur ne le lit.

C’est de loin la raison la plus fréquente de le convertir : non pas que le format soit mauvais, mais que l’endroit où vous voulez montrer le fichier ne sache pas le lire.

TOML est fait pour être ouvert et modifié. Gardez le fichier dans ce format tant que le travail dure, et exportez depuis lui chaque fois qu’une version finie est nécessaire.

TOML ressemble à INI et se comporte comme un format de données. Une valeur écrite 30 est un entier, 30.0 est un flottant, true est un booléen, « 30 » est une chaîne, et 2026-08-05 est une date — le format les définit tous, donc chaque analyseur est d’accord et aucun programme n’a à deviner ce que voulait l’auteur.

Cette seule propriété est la plus grande partie de la raison pour laquelle il existe. Les bugs de configuration se concentrent exactement sur cette ambiguïté : un drapeau lu comme la chaîne « false » et trouvé truthy, un numéro de version silencieusement converti en flottant, un numéro de port qui arrive sous forme de texte. Un format avec des types supprime toute la catégorie.

YAML est plus puissant et bien plus facile à se tromper, et TOML a été écrit en réponse directe à cela. La structure en YAML s’exprime par l’indentation, donc une espace mal placée change le sens d’un document sans produire d’erreur, et le fichier s’analyse quand même — en quelque chose d’autre que ce qui était voulu.

Vient ensuite l’inférence de type. Les anciens YAML lisent no comme un booléen, donc un code pays, un champ de langue ou une colonne de réponse devient false. Les numéros de version comme 1.20 deviennent le flottant 1.2. Une chaîne qui ressemble à un horaire devient un nombre sexagésimal. Chacun de ces cas a causé de vraies pannes. TOML n’a aucun d’eux : la structure est explicite, et une valeur est ce que sa syntaxe dit qu’elle est.

Rust l’a répandu partout le premier — tout projet Cargo possède un Cargo.toml — et Python a suivi de manière décisive : pyproject.toml est désormais l’emplacement standard de la configuration de build, et le langage embarque un lecteur TOML dans sa bibliothèque standard.

Au-delà de cela, Hugo et plusieurs générateurs de sites statiques, Netlify, Poetry, Ruff, et un flux régulier d’outils plus récents qui voulaient une configuration qu’un humain puisse éditer sans le risque de l’indentation. Il est devenu le choix par défaut pour la configuration destinée aux développeurs à peu près de la manière dont YAML est devenu celui de l’infrastructure.

Un en-tête entre crochets est une table, qui est le mot de TOML pour une section. L’imbrication se fait avec un point : [tool.ruff.lint] déclare une table à l’intérieur d’une table à l’intérieur d’une table, et les points sont de la structure plutôt que des éléments d’un nom — ce qui est précisément l’endroit où INI s’arrête et où TOML continue.

Les doubles crochets sont la partie qui piège tout le monde. [[bin]] répété trois fois ne redéfinit pas une table trois fois ; il déclare un tableau de tables, trois entrées dans une liste. C’est ainsi qu’on exprime « plusieurs du même type de chose » — trois binaires, quatre dépendances, une liste d’auteurs — et si une configuration est silencieusement écrasée plutôt qu’accumulée, des crochets simples là où des doubles auraient dû se trouver en est presque toujours la raison.

Il existe aussi des tables définies sur une seule ligne entre accolades : name = { first = "Ada", last = "Lovelace" }. C’est l’équivalent du format JSON, et c’est utile pour les petits groupes de paramètres que l’on veut garder ensemble sans leur consacrer un en-tête complet.

Les tables en ligne peuvent s’imbriquer, et un tableau de tables en ligne se construit avec la même notation entre crochets à l’intérieur d’accolades. Cela donne un style très proche du JSON pour les cas où la lisibilité compte moins que la compacité, et c’est pourquoi la plupart des fichiers qui en utilisent mélangent les deux styles selon ce qui rend le mieux à l’endroit considéré.

Les chaînes multilignes utilisent trois guillemets de chaque côté, et ce qu’elles contiennent est pris tel quel, sans interprétation des séquences d’échappement. C’est utile pour les blocs de configuration qui contiennent des expressions régulières ou des chemins Windows avec beaucoup d’antislashs, où l’échappement classique devient rapidement illisible.

TOML comprend les dates et les heures directement : une date seule, une heure seule, et un horodatage avec ou sans décalage. Ce sont des valeurs au même titre que les entiers, pas des chaînes que quelque chose doit analyser ensuite.

C’est une petite fonctionnalité qui supprime une contrariété persistante. Une configuration contenant une date de publication, une expiration, une échéance ou un planning n’a plus besoin d’un format de chaîne convenu documenté dans un commentaire et réimplémenté chez chaque consommateur. Le format le spécifie, et l’analyseur rend une date.

La représentation suit ISO 8601, ce qui veut dire que les fuseaux horaires et les décalages s’écrivent de la même manière que dans le reste de l’écosystème. Pour des configurations distribuées internationalement, c’est une garantie que la valeur écrite et la valeur lue par un programme à l’autre bout du monde sont les mêmes.

Les données profondément imbriquées. TOML est conçu pour être plat et lisible, et dès que la structure descend à trois ou quatre niveaux, les noms d’en-têtes deviennent longs et le fichier devient plus difficile à suivre que le JSON qu’il cherche à remplacer. Si votre configuration ressemble à un arbre de documents, elle devrait probablement en être un.

Les données générées par machine sont l’autre cas. TOML est fait pour des fichiers que des humains éditent ; JSON est fait pour des fichiers que des programmes échangent, et il est plus petit, plus rapide à analyser et pris en charge partout. Utiliser TOML comme format d’échange de données est possible et n’apporte rien — la lisibilité qu’il optimise ne vaut la peine d’être payée que lorsqu’un humain lit le fichier. Pour un service qui sérialise son état interne, JSON ou YAML reste le bon choix, et forcer TOML dans ce rôle ajoute des frictions sans bénéfice.

N’importe quel éditeur de texte, et un éditeur qui prend en charge TOML vaut la peine d’être utilisé pour tout ce qui est substantiel — il signalera immédiatement une chaîne non terminée ou un en-tête de table mal formé, là où un analyseur le signalera comme un échec plusieurs lignes plus loin.

Deux habitudes préviennent la plupart des erreurs. Gardez chaque clé dans l’en-tête de table auquel elle appartient, puisqu’une clé écrite au-dessus du premier en-tête se retrouve au niveau racine et ne fait silencieusement rien. Et ne mettez pas de guillemets autour des nombres ou des booléens : les guillemets en font des chaînes, le programme compare ensuite une chaîne à un booléen, et le réglage semble ignoré sans raison visible.