Introduction
Dwarf Therapist is a powerful external management tool for Dwarf Fortress, but most players interact only with its visual interface and never explore the configuration layer underneath it.
The config file and default settings control how the application behaves, what data it displays, and how it organizes your dwarf roster. Understanding these settings gives you meaningful control over the tool beyond basic point-and-click labor management.
You can define custom roles, adjust display behavior, set default labor states for new dwarves, and resolve persistent issues that the interface alone cannot fix.
This guide explains every major component of the Dwarf Therapist configuration system, what each setting does, where the relevant files are located, and how to modify them safely and effectively.
Quick Facts about Dwarf Therapist Config File
- The Dwarf Therapist config file is a plain text file stored in the application’s installation directory or a platform-specific user data folder
- Configuration files use INI or JSON formatting depending on the Dwarf Therapist version, and are fully human-readable without special software
- Default settings define the initial state of labor assignments, display columns, refresh intervals, and role templates when no user customization has been applied
- Changes to the config file take effect after restarting Dwarf Therapist; edits made while the application is running will be overwritten on close in some versions
- Always create a backup copy of the config file before editing it manually
- Role definitions stored in the config file allow players to create reusable labor profiles that can be applied to any dwarf in one action
- Display settings control which columns appear in the labor grid, column ordering, and color coding for skill levels and mood states
- Deleting or corrupting the config file will reset Dwarf Therapist to factory defaults but will not affect Dwarf Fortress save data
- Memory layout files are separate from the main config file and are not discussed in this guide; they serve a different function
- Platform-specific config file paths differ between Windows, macOS, and Linux installations
What the Dwarf Therapist Config File Contains
File Location and Structure Overview
The config file location varies depending on your platform and how Dwarf Therapist was installed. On Windows, the file is typically found in the same directory as the Dwarf Therapist executable, named DwarfTherapist.ini or preferences.ini depending on the version.
On Linux, the file is commonly stored in the hidden .config directory within the user’s home folder, under a path such as ~/.config/DwarfTherapist/DwarfTherapist.conf.
On macOS, it may be located in ~/Library/Preferences/ or within the application bundle depending on how the build was compiled.
The file is structured in sections, each marked with a bracketed header such as [MainWindow] or [Labor]. Each section contains key-value pairs that define specific behaviors. A typical entry looks like this:
[MainWindow]
window_width=1200
window_height=800
show_toolbar=trueUnderstanding this structure makes manual editing straightforward. Each key has a defined purpose, and values are constrained to expected types such as integers, booleans, or strings. Entering an invalid value type for a key will usually cause Dwarf Therapist to fall back to its built-in default for that setting.
Core Settings Sections and What They Control
The config file is organized into logical sections that correspond to different areas of the application. The most commonly relevant sections for players are MainWindow, Labors, Roles, Display, and General.
The MainWindow section stores the application window’s saved position and size, whether the toolbar and sidebar panels are visible, and the last-used column sort order. These settings are updated automatically each time you close the application, so manual editing of this section is rarely necessary.
The Labors section is where default labor states are defined. Each labor has a corresponding key that determines whether it is enabled or disabled by default when Dwarf Therapist first reads a dwarf that has no prior configuration.
This section directly influences how new migrants appear in the labor grid when they arrive at your fortress. The Display section controls visual presentation including column visibility, color thresholds for skill level highlighting, and whether mood indicators are shown inline with dwarf names.
Adjusting these settings can meaningfully improve readability for large fortresses with dense labor grids.
The General section contains application-level settings such as the memory polling interval, whether Dwarf Therapist should auto-refresh when new dwarves are detected, and logging verbosity for troubleshooting purposes.
How Default Settings Affect Your Labor Grid
Factory Defaults and What They Mean in Practice
When Dwarf Therapist is installed fresh with no prior configuration, the factory defaults determine how every element of the interface is presented. These defaults are embedded in the application binary and represent the developer’s judgment about a reasonable starting state for a new user.
By default, most labors are neither universally enabled nor universally disabled in the grid display. The tool presents the current state of each dwarf’s labor as it appears in the game, rather than imposing its own starting values.
This means the grid on first launch reflects whatever labor states your dwarves already have from in-game assignment or vanilla defaults. The refresh interval defaults to a moderate polling rate, typically a few seconds between memory reads.
This balances responsiveness with system resource usage. For players managing very large fortresses, lowering the polling interval can make the grid feel more reactive. For players on lower-end hardware, increasing it reduces background CPU usage.
Color-coding defaults assign visual distinctions to skill-level ranges, helping players quickly identify which dwarves are novices versus experts in any given labor column.
These thresholds can be adjusted in the Display section if the default ranges do not match your preferred visibility style.
Role Definitions and How They Interact With Default Settings
Roles in Dwarf Therapist are named labor bundles that you can define once and apply to any dwarf with a single action. A role called Farmer might enable agriculture, plant gathering, and food hauling while disabling everything else. A role called Dedicated Smith might enable only metalsmithing and related hauling labors.
Role definitions are stored in the config file’s Roles section. Each role entry specifies a name, a list of enabled labors, and optionally a list of explicitly disabled labors.
When you apply a role to a dwarf, Dwarf Therapist writes those labor states directly to the game’s memory for that dwarf.
Default roles shipped with Dwarf Therapist cover common fortress archetypes and provide a useful starting point. They are fully editable and can be replaced with custom definitions suited to your particular fortress management style.
Common problems with default settings and how to resolve them:
- Labor grid shows all dwarves with identical default states: The config file may have been reset to factory defaults; check whether your customized file was overwritten during a Dwarf Therapist update
- New migrants always appear with unexpected labor assignments: Review the Labors section of the config file to confirm default labor states match your intended starting profile
- Color coding makes skill levels difficult to distinguish: Edit the Display section threshold values to widen the ranges between color bands
- Application window resets position on every launch: The MainWindow section may not be saving correctly; check write permissions on the config file location
- Custom roles disappear after updating Dwarf Therapist: Updates can overwrite the config file; always back up your config before updating and merge your custom roles into the new default file manually
Editing the Config File Safely and Effectively
Manual Editing Best Practices
Manual configuration file editing gives you precise control over settings not exposed through the graphical interface. Before making any changes, copy the existing config file to a backup location named DwarfTherapist.ini.backup.
Open the config file in a plain text editor. On Windows, Notepad works but a code-aware editor such as Notepad++ or VS Code will highlight structure more clearly and reduce the risk of accidental formatting errors. On Linux and macOS, any terminal-based or GUI text editor is suitable.
Edit only the key-value pairs you intend to change. Avoid altering section headers, removing keys entirely, or changing the file encoding. Most config parsers used by Qt applications expect UTF-8 encoding without a byte order mark; saving in the wrong encoding can cause the entire file to be ignored on next launch.
After saving your edits, launch Dwarf Therapist and verify that the changes took effect as expected.
If the application behaves unexpectedly or fails to launch, replace the edited file with your backup and repeat the process with more conservative changes.
Creating and Customizing Role Definitions
Adding a custom role to the config file involves creating a new entry in the Roles section following the format used by existing role entries. The structure varies slightly across Dwarf Therapist versions but generally follows a pattern of a named block containing a list of labor identifiers, each set to true or false.
A minimal custom role entry for a hauler-only profile might look like this:
[Roles/HaulerOnly]
name=Hauler Only
labors\1\active=true
labors\2\active=false
labors\3\active=trueLabor identifier numbers correspond to the internal labor index used by Dwarf Therapist, as documented in the application’s source code and community reference guides.
Cross-referencing the labor names visible in the grid with the internal index list is the most reliable way to build accurate role definitions.
After saving the updated config file and restarting Dwarf Therapist, your custom role will appear in the role assignment dropdown alongside the built-in defaults. Applying it to a dwarf will immediately update their labor assignments in the live game session.
| Config Section | What It Controls | Edit Frequency | Risk Level If Misconfigured |
| MainWindow | Window size, position, panel visibility | Rarely needed manually | Low, visual only |
| Labors | Default labor states for new dwarves | Occasionally | Medium, affects new migrant assignments |
| Roles | Named labor bundle definitions | When customizing workflow | Low, roles can be deleted and recreated |
| Display | Color thresholds, column visibility | Personal preference | Low, visual only |
| General | Polling interval, auto-refresh, logging | Performance tuning | Medium, affects responsiveness |
Frequently Asked Questions
Where exactly is the Dwarf Therapist config file located on each platform?
On Windows it is typically in the same folder as the executable or in %APPDATA%\DwarfTherapist. On Linux it is usually at ~/.config/DwarfTherapist/DwarfTherapist.conf. On macOS it may be in ~/Library/Preferences/ or
within the application support folder. The exact path can also be found by checking the application’s About or Help menu in some versions.
Will editing the config file affect my Dwarf Fortress save data?
No. The config file controls only Dwarf Therapist’s own behavior and display preferences. It has no connection to Dwarf Fortress save files.
Even deleting the config file entirely will not affect your fortress saves. The only consequence of a deleted config file is that Dwarf Therapist resets to factory defaults on its next launch.
What happens if I introduce a formatting error into the config file?
Dwarf Therapist typically ignores malformed sections or keys and falls back to its built-in default for that setting. In some cases a severely corrupted file will cause the application to reset the entire config to defaults on launch.
This is why maintaining a clean backup before every manual edit session is strongly recommended.
Can I share my config file with other players?
Yes. Most sections of the config file are platform-independent in content. Role definitions, display preferences, and labor defaults will transfer correctly between players using the same Dwarf Therapist version.
Platform-specific path settings in the MainWindow section may need adjustment when moving a config file between operating systems.
How do I reset Dwarf Therapist to its factory defaults without reinstalling?
Delete or rename the existing config file and launch Dwarf Therapist. The application will generate a fresh config file with all factory defaults on startup.
This is the cleanest way to resolve persistent configuration issues without going through a full reinstallation.
Do custom roles survive Dwarf Therapist updates?
Not automatically. Updates may overwrite the config file depending on how the installer or package manager handles existing files. Before updating, copy your config file to a safe location.
After updating, compare your backed-up file with the new default and manually transfer your custom role definitions into the updated config.
What is the polling interval setting and how should I adjust it?
The polling interval controls how frequently Dwarf Therapist reads the Dwarf Fortress process memory to refresh the display. A lower value means more frequent updates and a more responsive grid, at the cost of slightly higher CPU usage.
A higher value reduces background processing but means changes in the game take longer to appear in the grid. For most modern systems, the default interval is appropriate. Adjust only if you notice performance issues or want a more real-time view
Can I have multiple config files for different fortress setups?
Dwarf Therapist loads a single config file per session, but you can maintain multiple config files manually and swap them before launching.
Name each config file to reflect the fortress or playstyle it is configured for, keep them in a dedicated folder, and copy the appropriate one to the expected config file location before each session. This is a manual process but gives full flexibility for players who manage very different fortress types.
Latest Post:
