Les fichiers de configuration de Darktable - Partie 1 / 2

jpverrue · Avril 28, 2026, 4:57

Ce document est également disponible en format PDF

Référence des fichiers de configuration et de fonctionnement de Darktable

À propos

Ce document décrit les fichiers et dossiers conformes à la version 5.4 de Darktable.

Les précédentes éditions mentionnaient la conformité avec les différentes versions de Darktable. Pour une lecture plus fluide, ces informations ont été supprimées, car les modifications entre les versions intervenues ne remettent pas fondamentalement en question le contenu de ce document qui reste tout à fait utilisable pour toutes les versions depuis la 3.8.
La version 5.4 ouvre la possibilité de créer de multiples espaces de travail dans Darktable. Cela amène la création de fichiers de configuration propres à chaque espace de travail. Chaque fichier en cause a été dupliqué. Le fichier original subsiste pour l’espace de travail par défaut. La copie est renommée en gardant le nom original augmenté du nom de l’espace de travail.

Préambule

Indépendamment de vos propres fichiers d’images, Darktable utilise un certain nombre de fichiers pour fonctionner. Ces fichiers sont de plusieurs ordres.

On distinguera d’abord les fichiers qui sont propres à chaque utilisateur de Darktable de ceux qui sont communs à tous les utilisateurs. Ces derniers sont fournis systématiquement avec chaque nouvelle version de Darktable. Les modifications que vous feriez sur ces derniers seront donc perdues lors de chaque mise à jour. Je les référencerai comme fichier utilisateur ou système.
On distinguera ensuite les fichiers de configuration qui régissent le fonctionnement du logiciel, des fichiers de traitement qui matérialisent toutes les modifications que vous faites sur vos photos. En effet, Darktable ne modifie JAMAIS vos fichiers d’images. Toutes vos modifications sont enregistrées dans ces fichiers de traitement. Je les référencerai respectivement comme fichier de configuration, ou de développement.
On distinguera enfin les fichiers de type “ texte ” qui n’ont besoin que d’un éditeur de texte pour être consultés ou modifiés, des fichiers de type “ binaire ” qui nécessitent des outils spécialisés pour être consultés ou modifiés. Je les référencerai également comme texte ou binaire.

Emplacement des fichiers.

Tous ces fichiers sont stockés à plusieurs endroits sur votre machine. Un endroit destiné essentiellement à vos propres fichiers que j’appellerai bien sûr le dossier Utilisateur ; un deuxième qui contient les vignettes de vos photos ainsi que quelques données d’exécution de Darktable que j’appellerai dossier Cache ; un troisième qui sera utilisé pour les enregistrements des journaux de débogage que j’appellerai dossier Temporaire ; un quatrième destiné aux fichiers système que j’appellerai dossier Système cela va de soi ! Et enfin, tous les dossiers qui contiennent des images que vous avez importées. Ces dossiers sont situés différemment selon le système que vous utilisez. Voici ces lieux décrits système par système. Vous pouvez aussi définir vous-même l’emplacement de ces dossiers grâce aux options de lancement de Darktable.

Sous Linux.

Remarque préliminaire : la variable $HOME contient le chemin absolu (à partir de la racine du système), du dossier personnel de l’utilisateur. C’est-à-dire, en général, /home/<login de l'utilisateur>. Cette variable est couramment utilisée dans les scripts et en mode ligne de commande. Elle n’est pas universellement utilisable dans les gestionnaires de fichiers graphiques ; par exemple, Nautilus ne la reconnaît pas alors que Dolphin la reconnaît. Je l’ai employée dans cette description, car c’est une façon assez élégante de décrire cette partie du chemin d’accès à des fichiers. Nota bene : le caractère ~ remplace avantageusement la variable $HOME en saisie ; de plus, il est utilisable partout.

Dossier Utilisateur :
$HOME/.config/darktable par défaut. Cet emplacement peut être modifié avec l’option de lancement --configdir.
Dossier Cache :
$HOME/.cache/darktable par défaut. Cet emplacement peut être modifié avec l’option de lancement --cachedir.
Dossier Temporaire :
/tmp par défaut. Cet emplacement peut être modifié avec l’option de lancement --tmpdir. L’emplacement des journaux de débogage peut aussi être modifié avec l’option --dumpdir.
Dossier Système :
/usr/share/darktable par défaut. Cet emplacement peut être modifié avec l’option de lancement --datadir. Si vous compilez vous-même la version la plus récente de Darktable, le dossier système se trouve par défaut dans /opt.

Les dossiers .config et .cache sont des dossiers cachés (le ‹ . › au début du nom). Pour y accéder, il suffit de taper leur nom. Voici les moyens pour les visualiser :

Dans un terminal : ls -a
Avec les outils graphiques, cela dépend de l’outil, mais le raccourci Ctrl+h permet le plus souvent de le voir.

Sous MacOS.

Remarque préliminaire : MacOS et Linux partagent le même ancêtre commun, UNIX. La remarque préliminaire concernant la variable $HOME, héritée d’UNIX, s’applique donc également ici.

Dossier Utilisateur :
$HOME/.config/darktable par défaut. Cet emplacement peut être modifié avec l’option de lancement --configdir.
Dossier Cache :
$HOME/.cache/darktable par défaut. Cet emplacement peut être modifié avec l’option de lancement --cachedir.
Dossier Temporaire :
/private/var/folders/h_/<hashcode>/T par défaut. Cet emplacement peut être modifié avec l’option de lancement --tmpdir. L’emplacement des journaux de débogage peut aussi être modifié avec l’option --dumpdir.
Dossier Système :
/Applications/darktable.app/Contents/Resources/share/darktable par défaut. Cet emplacement peut être modifié avec l’option de lancement –-datadir.

Les dossiers .config et .cache sont des dossiers cachés (le ‹ . › au début du nom). Pour y accéder, il suffit de taper leur nom. Pour y accéder, il y a plusieurs méthodes selon qu’on utilise un terminal ou le “ Finder ”. Plusieurs de ces méthodes sont décrites dans ce fil de discussion

Sous Windows.

Dossier Utilisateur :
%LOCALAPPDATA%\darktable par défaut. Cet emplacement peut être modifié avec l’option de lancement --configdir
Dossier Cache :
L’emplacement par défaut est (était ? Changement de version de Windows ?)
%LOCALAPPDATA%\Microsoft\Windows\Temporary Internet Files\darktable\ Je l’ai vu aussi ici (version de Windows ?) : %LOCALAPPDATA%\Microsoft\Windows\NetCache\darktable\ Cet emplacement peut être modifié avec l’option de lancement --cachedir.
Dossier Temporaire :
%LOCALAPPDATA%\Temp\ par défaut.
Sous Windows, le dossier dans lequel Darktable écrira les fichier journaux est différent du dossier temporaire. Précédemment ces fichiers étaient enregistrés dans les sous-dossiers système du profil de l’utilisateur, ainsi que dans un répertoire caché (il était donc impossible de cliquer dessus dans l’explorateur de fichiers avec les paramètres système par défaut). C’est emplacement a été modifié en %USERPROFILE%\Documents\Darktable.

Cet emplacement peut être modifié avec l’option de lancement --tempdir.
Il peut aussi être modifié avec l’option de lancement --dumpdir.
Dossier Système :
C:\Program Files\darktable\share\darktable\ par défaut. Cet emplacement peut être modifié avec l’option de lancement –-datadir.

La variable %LOCALAPPDATA% correspond au chemin des fichiers de configuration des applications propres à chaque utilisateur. C’est-à-dire, en général, C:\Users\<login de l'utilisateur>\AppData\Local\.

Comme pour Linux et MacOS, j’ai utilisé la notation lisible dans une fenêtre de commande (terminal ou cmd). Donc “Users” et “Program Files”. Ces noms apparaîtront cependant sous une forme francisée dans l’explorateur de fichier : “ Utilisateurs ” et “ Programmes ”. Le dossier AppData est un dossier caché. Pour l’afficher, passer par les options de l’explorateur : organiser → options des dossiers et de recherche → affichage → afficher les fichiers, dossiers et lecteurs cachés.

Description des fichiers.

Fichiers du dossier Utilisateur.

Voici la liste alphabétique des fichiers contenus dans ce dossier avec la description de leur rôle. Ils ne sont pas obligatoirement tous présents sur votre installation, car ils se créent au fil du temps et des besoins ; parfois même, leur création nécessite une intervention manuelle.

color
Dossier utilisateur contenant les éventuels profils de couleur d’entrée et/ou de sortie. Ce dossier ne contient pas directement les profils. Il contient uniquement deux dossiers in et out. Les dossiers color, color/in et color/out ne sont pas créés automatiquement lors de la configuration initiale de Darktable. Si vous avez besoin de ces dossiers pour y déposer des profils, vous devez les créer.
- color/in
  Dossier utilisateur contenant les profils de couleur d’entrée. Ces fichiers de profil sont au format ICC.
- color/out
  Dossier utilisateur contenant les profils de couleur de sortie. Ces fichiers de profil sont au format ICC.
darktablerc
| Utilisateur | Configuration | Texte |
Fichiers contenant les données de configuration du logiciel. La plupart des données de configuration contenues dans ces fichiers peuvent être modifiées via les différents onglets de la fenêtre « préférences » de Darktable. Il existe cependant quelques valeurs très peu utilisées ou « un peu trop sensibles » qui ne sont manipulables que par la modification de ces fichiers. Darktable réécrit ces fichiers chaque fois que l’on quitte le logiciel. Les éventuelles personnalisations doivent donc se faire quand Darktable n’est pas actif.
- darktablerc-common
  Fichier contenant les données de configuration du logiciel communes à tous les espaces de travail.
- darktablerc
  Fichier contenant les données de configuration du logiciel pour l’espace de travail par défaut.
- darktablerc-<nom-de-l-espace>
  Fichier contenant les données de configuration du logiciel pour l’espace de travail <nom-de-l-espace>.
data.db
| Utilisateur | Développement | Binaire |
Fichier qui contient la seconde partie de la Base de Données (BdD). Contient les mots-clés, les styles, les préréglages, la géolocalisation. L’emplacement de ce fichier peut être modifié avec l’option de lancement –-library. L’utilisation de cette option modifiera simultanément l’emplacement de data.db et de library.db. Fichier au format SQLite. Ce fichier est commun à tous les espaces de travail.
data.db.lock
| Utilisateur | Configuration | Texte |
Fichier de verrouillage de la seconde partie de la BdD. Il est créé au moment de l’ouverture de celle-ci et supprimé lors de sa fermeture. Dans de rares cas, Darktable ne peut pas supprimer ce fichier avant de s’arrêter. S’il subsiste, le prochain lancement de Darktable avortera puisque celui-ci considérera que la BdD est déjà ouverte par un autre logiciel. Dans ce cas, la suppression de ce fichier .lock réglera le problème. Il contient le « Process Id » du processus qui a ouvert la BdD. Ce fichier suit le fichier data.db. Si l’emplacement de data.db a été modifié avec l’option –-library, l’emplacement du fichier de verrouillage le sera également. Ce ficier est commun à tous les espaces de travail.
data.db-pre-<version>
| Utilisateur | Développement | Binaire |
L’installation d’une nouvelle version majeure de Darktable nécessite parfois (souvent) une modification du schéma de la base de données rendant incompatible la BdD avec la version antérieure. Avant cette modification, une sauvegarde est créée automatiquement par copie du fichier data.db. Ce fichier peut être supprimé s’il n’est pas envisagé de retour vers une version antérieure. Dans le nom de ce fichier, <version> correspond au numéro de la nouvelle version de Darktable en cours d’installation. Fichier au format SQLite. Ce ficier est commun à tous les espaces de travail.
data.db-snp-<date>
| Utilisateur | Développement | Binaire |
Ces fichiers contiennent des instantanés (snapshots en anglais, d’où l’abréviation snp) de la BdD. C’est-à-dire, une sauvegarde de la BdD faite automatiquement et à cadence régulière, afin de pouvoir revenir à une situation correspondant à la date mentionnée dans le nom du fichier. La date est enregistrée sous forme compacte - sans séparateurs -, selon la séquence suivante AAAAMMJJhhmmss. Vous pouvez régler les paramètres de maintenance de la BdD dans la fenêtre des préférences de Darktable → onglet stockage → paragraphe base de données. Fichier au format SQLite. Ce fichier est commun à tous les espaces de travail.
library.db
| Utilisateur | Développement | Binaire |
Fichiers qui contienent la première partie de la BdD. Ces fichiers contienent toutes les données de développement. L’emplacement de ces fichiers peut être modifié avec l’option de lancement –-library. L’utilisation de cette option modifiera simultanément l’emplacement des fichiers data.db et library.db. Fichiers au format SQLite.
- library.db
  Fichier qui contient la première partie de la BdD pour l’espace de travail par défaut.
- library-<nom-de-l-espace>.db
  Fichier qui contient la première partie de la BdD pour l’espace de travail <nom-de-l-espace>.
library.db.lock
| Utilisateur | Configuration | Texte |
Fichiers de verrouillage de la première partie de la BdD. Lire les précisions concernant le fichier data.db.lock ci-dessus. Si l’emplacement des fichiers library.db a été modifié avec l’option –-library, l’emplacement des fichiers de verrouillage le sera également.
- library.db.lock
  Fichier de verrouillage de la première partie de la BdD pour l’espace de travail par défaut.
- library-<nom-de-l-espace>.db.lock
  Fichier de verrouillage de la première partie de la BdD. pour l’espace de travail <nom-de-l-espace>.
library.db-pre-<version>
| Utilisateur | Développement | Binaire |
Fichiers de reprise de la première partie de la BdD. L’installation d’une nouvelle version majeure de Darktable nécessite souvent une modification du schéma de la base de donnée rendant incompatible la BdD avec la version antérieure. Avant cette modification, une sauvegarde est créée automatiquement par copie des fichiers library.db. Ces fichiers peuvent être supprimés s’il n’est pas envisagé de retour vers une version antérieure. Dans le nom, <version> correspond au numéro de la nouvelle version de Darktable en cours d’installation. Fichiers au format SQLite.
- library.db-pre-<version>
  Fichier de reprise de la première partie de la BdD pour l’espace de travail par défaut.
- library-<nom-de-l-espace>.db-pre-<version>
  Fichier de reprise de la première partie de la BdD pour l’espace de travail <nom-de-l-espace>.
library.db-snp-<date>
| Utilisateur | Développement | Binaire |
Fichiers de sauvegarde de la première partie de la BdD. Ces fichiers contiennent des instantanés (snapshots en anglais, d’où l’abréviation « snp ») de la BdD. C’est-à-dire, des sauvegardes de la BdD faites automatiquement et à cadence régulière, afin de pouvoir revenir à une situation correspondant à la date mentionnée dans les noms des fichiers. La date est enregistrée sous forme compacte – sans séparateurs –, selon la séquence suivante AAAAMMJJhhmmss. Vous pouvez régler les paramètres de maintenance de la BdD dans la fenêtre des préférences de Darktable → onglet stockage → paragraphe base de données. Fichiers au format SQLite.
- library.db-snp-<date>
  Fichiers de sauvegarde de la première partie de la BdD pour l’espace de travail par défaut.
- library-<nom-de-l-espace>.db-snp-<date>
  Fichiers de sauvegarde de la première partie de la BdD pour l’espace de travail <nom-de-l-espace>.
lua
Dossier utilisateur contenant les éventuels scripts additionnels, ceux que vous avez importés comme ceux que vous avez éventuellement créés. Les scripts sont écrits en langage Lua. Pour découvrir Lua, outre le site lua.org, vous disposez sur le site darktable.org d’un chapitre dans le manuel de Darktable ainsi que d’un manuel dédié . Le dossier lua n’est pas créé automatiquement lors de la configuration initiale de Darktable. « Le script manager » le créera pour vous si vous importez les scripts proposés et packagés par la communauté. Si vous avez besoin d’y déposer vos propres scripts et qu’il n’a pas été créé par le script manager, vous devez le créer.
luarc
| Utilisateur | Configuration | Texte |
Fichier qui contient la liste des scripts Lua à charger lors du lancement de Darktable. « Le script manager » créera et modifiera ce fichier pour vous si vous importez les scripts proposés et packagés par la communauté. Sinon, pour intégrer vos propres scripts, il faudra le créer ou le modifier vous-même avec un éditeur de texte, en respectant strictement la syntaxe du langage Lua. Pour créer des scripts, voir des exemples dans le manuel de référence Lua disponible sur lua.org ainsi que le dans le manuel de Darktable et le manuel dédié aux scripts Lua sur le site darktable.org.
presets.json
| Utilisateur | Configuration | Texte |
Fichier contenant les profils de bruits calculés par l’utilisateur en vue d’effectuer des tests. Ce fichier n’existe que si vous l’avez copié vous-même à cet endroit. Il est le résultat du calcul du profil de bruit d’un boîtier. Ce fichier est au format json.
shortcutsrc
| Utilisateur | Configuration | Texte |
Fichier qui contient les raccourcis clavier, éventuellement personnalisés. Les raccourcis peuvent tous être modifiés via l’onglet “raccourcis” de la fenêtre “préférences” de Darktable ou via la fenêtre dédiée accessible via l’icône représentant un clavier.
shortcutsrc.backup
| Utilisateur | Configuration | Texte |
Fichier qui contient les valeurs sauvegardées des raccourcis, lors d’une modification de ceux-ci.
shortcutsrc.default
| Utilisateur | Configuration | Texte |
Fichier qui contient les valeurs par défaut des raccourcis. C’est le seul fichier système qui est stocké dans le dossier utilisateur.
shortcutsrc.edit
| Utilisateur | Configuration | Texte |
Fichier utilisé par la boite de dialogue « restauration raccourci »
styles
Dossier utilisateur contenant les fichiers de styles que vous avez créés. La suppression d’un de vos styles dans Darktable ne supprime pas le fichier dans ce répertoire. Le dossier styles n’est pas créé automatiquement lors de la configuration initiale de Darktable. Il est créé par Darktable quand vous créez un premier style. Il n’est pas nécessaire d’y déposer les styles que vous importez.
- <vos styles>.dtstyle
  | Utilisateur | Développement | Texte |
  Les fichiers du dossier styles sont des fichiers au format xml, mais le contenu, bien que de format texte, est plutôt un BLOB (Binary Large OBject), donc non modifiable. Ces fichiers sont suffixés avec l’extension “.dtstyle”.
themes
Dossier utilisateur contenant les éventuels fichiers de configuration personnalisés de l’aspect de l’interface de Darktable. Ces fichiers sont au format CSS (Cascading Style Sheet) tel que décrit par le W3C. Cependant, toutes les fonctionnalités CSS ne sont pas prises en charge par l’interface graphique Gtk utilisée par Darktable. Si vous avez besoin de ce dossier pour y déposer vos propres feuilles de styles, vous devez le créer.
- <vos thèmes>.css
  | Utilisateur | Configuration | Texte |
  Fichier(s) CSS. Le nommage est libre, mais il est recommandé d’utiliser un nom de fichier différent des fichiers de style fournis par défaut (voir ci-dessous le dossier thèmes dans le chapitre ‘Fichiers du dossier système’). Si vous complétez ou modifiez un de ces fichiers, ne le copiez pas en totalité. Créez votre fichier, commencez-le par une instruction d’importation telle que décrite dans la norme CSS, puis ajoutez simplement vos modifications.
user.css
| Utilisateur | Configuration | Texte |
Fichier CSS. Ce fichier contient les personnalisations des feuilles de style que vous faites à partir de la fenêtre des préférences de Darktable → onglet général → option « modifier le thème via les ajustements CSS ci-dessous » et la zone de saisie située juste en dessous.
watermarks
Dossier utilisateur contenant les fichiers des filigranes. Ces fichiers doivent être au format SVG. Ils peuvent être créés avec n’importe quel outil capable de produire ce type de format de fichier. Le dossier watermarks n’est pas créé automatiquement lors de la configuration initiale de Darktable. Si vous avez besoin de ce dossier pour y déposer des fichiers de filigranes, vous devez le créer.

(Lire la suite dans le sujet « Les fichiers de configuration de Darktable - partie 1/2 »)