How to Install Dwarf Therapist on macOS & Linux

Table of Contents

Introduction

Dwarf Therapist is one of the most widely used companion tools for Dwarf Fortress, offering an external labor and skill management interface that the base game simply does not provide.

While Windows users have historically had the most straightforward installation experience, macOS and Linux players have their own reliable paths to get the tool running correctly. Understanding the installation process on these platforms requires some familiarity with terminal commands, package managers, and version compatibility.

None of this is particularly complex, but it does require following steps in the correct order. Skipping or reordering steps is the most common reason installations fail. This guide walks through the complete Dwarf Therapist installation process for both macOS and Linux, covering prerequisites, compatibility checks, build requirements, and post-installation configuration.

Whether you are running the Steam release of Dwarf Fortress or the classic Bay 12 version, the guidance here applies to both.

Quick Facts How to Install Dwarf Therapist on macOS & Linux

Dwarf Therapist is a free, open-source utility hosted on GitHub that requires manual installation on macOS and Linux
It reads Dwarf Fortress memory in real time and does not modify save files or game executables
macOS installation typically requires building from source using Homebrew and Xcode Command Line Tools
Linux installation is available via package manager on some distributions, or by building from source using Qt and CMake
Version matching is mandatory: Dwarf Therapist must correspond exactly to your installed version of Dwarf Fortress
Compatible with both the Steam release and the classic Bay 12 Games version of Dwarf Fortress
macOS support varies by release; not every Dwarf Therapist version includes a prebuilt macOS binary
Always launch Dwarf Fortress first before opening Dwarf Therapist to allow proper process detection
The tool requires read and write access to the Dwarf Fortress process memory, which may require adjusting system permissions on some platforms
Community forums including the Bay 12 Games forum and the r/dwarffortress subreddit are reliable sources for platform-specific troubleshooting

What You Need Before Installing Dwarf Therapist

System Requirements and Dependencies

Before attempting installation on either platform, confirming that your system meets the necessary prerequisites will save significant troubleshooting time later. Dwarf Therapist is a Qt-based application, meaning it depends on the Qt framework being available either as a prebuilt dependency or compiled alongside the tool.

On macOS, the required dependencies are Xcode Command Line Tools, Homebrew, Qt 5 or Qt 6 depending on the Dwarf Therapist version, and CMake.

These are all freely available and installable through standard channels. macOS versions from Monterey onward have been the most commonly tested, though some users have reported success on older releases with additional configuration steps.

On Linux, requirements vary by distribution. The core dependencies across most distributions include Qt5 or Qt6 development libraries, CMake version 3.12 or higher, a working C++ compiler such as GCC or Clang, and the Git command line tool for cloning the repository. Many distributions also require the libqt5x11extras package or its Qt6 equivalent for proper window integration.

Check your installed version of Dwarf Fortress before proceeding. The version number is visible on the in-game main menu and in the game’s installation folder.

You will need this version number to select the correct Dwarf Therapist release from the GitHub releases page.

Finding the Correct Dwarf Therapist Version

The Dwarf Therapist project is maintained on GitHub, with an official repository under the username mifki and several community forks. The releases page lists each version, with notes indicating which Dwarf Fortress versions it supports.

This compatibility information is not always prominently displayed, so reading the release notes carefully is important. For the Steam version of Dwarf Fortress, look for release notes that explicitly mention Steam or the specific numerical version matching your game.

For the classic Bay 12 version, the version number format differs slightly and will be noted separately in compatible Dwarf Therapist releases. If no prebuilt binary is available for your platform in a given release, you will need to build from source using the steps below. This is a common situation for macOS users in particular, where prebuilt binaries are not consistently provided across all releases.

How to Install Dwarf Therapist on macOS

Installing Dependencies with Homebrew

The most reliable installation method on macOS uses Homebrew to manage dependencies before building Dwarf Therapist from source. If Homebrew is not already installed, open Terminal and run the installation command from the official Homebrew website at brew.sh.

The installation script handles everything required and does not need elevated permissions beyond what it requests during setup. Once Homebrew is available, install the required dependencies by running the following commands in Terminal one at a time:

brew install cmake

brew install qt@5

brew install git

After installation, Qt needs to be added to your PATH so that the build system can locate it. Add the following line to your shell configuration file, which will be .zshrc on most modern macOS installations:

export PATH="/opt/homebrew/opt/qt@5/bin:$PATH"

After saving that change, reload your shell configuration by running:

source ~/.zshrc

Confirm that Qt is accessible by running:

qmake --version

If a version number is returned, the dependency is correctly installed and visible to the build system. If the command is not found, revisit the PATH configuration step before continuing.

Building and Running Dwarf Therapist on macOS

With dependencies in place, clone the Dwarf Therapist repository from GitHub. Navigate in Terminal to a directory where you want to store the project files, then run:

git clone https://github.com/Dwarf-Therapist/Dwarf-Therapist.git

cd Dwarf-Therapist

Create a build directory to keep compiled files organized separately from source files:

mkdir build

cd build

Run CMake to configure the build, then compile:

cmake ..

make -j4

The -j4 flag runs four parallel compile jobs, which speeds up the process on most modern machines. Adjust this number based on your available CPU cores if preferred.

Once compilation completes, the Dwarf Therapist application bundle will be located inside the build directory. Before launching it, Dwarf Fortress must already be running with a fortress loaded or a game in progress. Open Dwarf Therapist from the build output location, and it will attempt to detect the running Dwarf Fortress process automatically.

On macOS, system privacy settings may block Dwarf Therapist from accessing another application’s memory.

If the tool fails to connect or shows no dwarves after loading, navigate to System Settings, then Privacy and Security, then accessibility or Input Monitoring depending on your macOS version, and grant Dwarf Therapist the necessary permissions. A system restart may be required after changing these settings.

Common problems and solutions specific to macOS installation:

CMake cannot find Qt: Confirm the Homebrew Qt installation path and re-export the PATH variable in your active terminal session
Build fails with compiler errors: Ensure Xcode Command Line Tools are installed by running xcode-select –install in Terminal
Dwarf Therapist launches but shows no dwarves: Dwarf Fortress may not be running or may still be on the main menu; load a game first, then refresh Dwarf Therapist
Permission denied errors at runtime: Grant the application Accessibility permissions in macOS System Settings
Application cannot be opened because it is from an unidentified developer: Right-click the application, select Open, and confirm in the dialog that appears

How to Install Dwarf Therapist on Linux

Package Manager Installation on Supported Distributions

Several Linux distributions include Dwarf Therapist in their official or community-maintained package repositories, which is the simplest installation path when available.

The package may not always correspond to the latest release, so confirming version compatibility with your installed Dwarf Fortress version before installing via package manager is important.

On Debian and Ubuntu-based distributions, check for availability with:

apt-cache search dwarf-therapist

If the package is listed, install it with:

sudo apt install dwarf-therapist

On Arch Linux and Arch-based distributions, Dwarf Therapist is available through the AUR (Arch User Repository). Using an AUR helper such as yay simplifies the process:

yay -S dwarf-therapist

On Fedora and RHEL-based distributions, availability through the default repositories is limited. Building from source, following the steps in the next section, is typically the most reliable path on these systems.

After installing the package manager, confirm the installed version number and verify that it matches your Dwarf Fortress version before running the tool. The version is usually displayed in the application’s About dialog or can be checked by running dwarf-therapist –version in a terminal.

Building Dwarf Therapist from Source on Linux

Building from source gives you control over which exact version is installed and is necessary on distributions where the package is unavailable or outdated.

Begin by installing build dependencies. The exact package names vary by distribution.

On Debian and Ubuntu based systems:

sudo apt install build-essential cmake git qtbase5-dev qtbase5-dev-tools libqt5x11extras5-dev

On Arch Linux:

sudo pacman -S base-devel cmake git qt5-base qt5-x11extras

On Fedora:

sudo dnf install gcc-c++ cmake git qt5-qtbase-devel qt5-qtx11extras-devel

With dependencies installed, clone the repository and navigate into it:

git clone https://github.com/Dwarf-Therapist/Dwarf-Therapist.git

cd Dwarf-Therapist

Create a build directory and compile:

mkdir build && cd build

cmake ..

make -j$(nproc)

The nproc command automatically uses all available CPU cores for compilation. Once complete, you can run Dwarf Therapist directly from the build directory with:

./DwarfTherapist

Alternatively, install it system-wide with:

sudo make install

On Linux, Dwarf Therapist requires the ability to attach to the Dwarf Fortress process using ptrace. Some distributions restrict this by default. If Dwarf Therapist fails to connect to a running Dwarf Fortress instance on Linux, this is the most likely cause.

To check whether ptrace restrictions are active, run:

cat /proc/sys/kernel/yama/ptrace_scope

A value of 1 or higher indicates restrictions are in place. To temporarily allow process attachment, run:

sudo sysctl kernel.yama.ptrace_scope=0

This change resets after reboot. To make it persistent, add the setting to /etc/sysctl.d/ by creating a configuration file with that parameter. Be aware that lowering ptrace scope has security implications on shared or multi-user systems. Apply this setting only on personal machines used for gaming.

Installation Method	macOS	Debian/Ubuntu	Arch Linux	Fedora
Package manager	Via Homebrew (deps only)	apt (version may lag)	AUR via yay	Limited availability
Prebuilt binary	Inconsistent by release	Inconsistent by release	AUR builds from source	Build from source
Build from source	Supported with Homebrew	Fully supported	Fully supported	Fully supported
Recommended path	Homebrew + source build	apt or source build	AUR or source build	Source build

Post-Installation Configuration and Verification

Confirming the Connection and Memory Layout

After installation on either platform, the first launch requires confirming that Dwarf Therapist is correctly reading game data. Launch Dwarf Fortress and load a fortress with at least a few dwarves present. Then open Dwarf Therapist.

The application should detect the running process within a few seconds and populate the main grid with your dwarf roster. If the dwarf grid remains empty or displays an error about an unrecognized game version, the memory layout file for your specific Dwarf Fortress version may be missing.

Memory layouts are stored in the /share/memory_layouts directory within the Dwarf Therapist installation folder. Community contributors publish updated layouts on the GitHub repository shortly after new Dwarf Fortress releases.

Download the appropriate layout file for your game version and place it in the memory layouts folder. Restart Dwarf Therapist with Dwarf Fortress running and the grid should populate correctly.

Keeping Dwarf Therapist Updated

When Dwarf Fortress releases an update, Dwarf Therapist will likely need an update as well before it can connect correctly. On Linux systems installed via package manager, running a standard system update will pull new versions when they become available in the repository.

On both platforms when using a source build, pulling the latest changes from the Git repository and recompiling is the update process.

cd Dwarf-Therapist

git pull

cd build

cmake ..

make -j$(nproc)

Monitoring the Dwarf Therapist GitHub repository for new releases is the most reliable way to know when an update is available. Watching the repository on your GitHub account will automatically notify you of new releases.

Frequently Asked Questions

Why does Dwarf Therapist show no dwarves after installation on macOS?

The most common cause is that Dwarf Fortress was not running or was still on the main menu when Dwarf Therapist launched. Load a fortress fully into an active game session, then reopen or refresh Dwarf Therapist.
If dwarves still do not appear, check macOS privacy permissions under System Settings and ensure Dwarf Therapist has been granted Accessibility access.

What is the ptrace_scope setting and why does it matter on Linux?

The ptrace_scope setting controls which processes are allowed to inspect or attach to other running processes. Dwarf Therapist needs to attach to the Dwarf Fortress process to read and write memory.
A ptrace_scope value of 1 or higher will block this attachment and prevent Dwarf Therapist from functioning. Temporarily setting it to 0 resolves this, with the security considerations noted in the installation section above.

Can I use Dwarf Therapist with the Steam version of Dwarf Fortress on Linux?

Yes, but the Steam version may have a different executable path than the classic Bay 12 version. Ensure you launch Dwarf Fortress through Steam so it runs as a standard process, and verify that the Dwarf Therapist version you have installed lists the correct Steam game version in its compatibility notes.

How do I know which version of Dwarf Therapist to install?

Check the version of Dwarf Fortress currently installed, visible on the in-game main menu. Then visit the Dwarf Therapist GitHub releases page and locate the release whose notes explicitly reference that Dwarf Fortress version number. Installing a mismatched version will result in incorrect data or a connection failure.

Is building from source on macOS complicated for users without development experience?

The process involves several terminal commands, but each step is straightforward when followed in the correct order. The most common stumbling point is the PATH configuration for Qt after installing via Homebrew.
Taking time to verify each dependency before proceeding to the build step avoids most common errors.

Will Dwarf Therapist affect the performance of Dwarf Fortress on my system?

Dwarf Therapist is a lightweight application with a minimal processing footprint. It polls game memory at intervals rather than continuously monitoring it, which keeps its CPU and memory usage low.
Players running Dwarf Fortress on systems with limited resources are unlikely to notice any measurable performance difference from running Dwarf Therapist alongside it.

What should I do if a new Dwarf Fortress update breaks my Dwarf Therapist installation?

Do not attempt to use Dwarf Therapist with an incompatible Dwarf Fortress version. Check the Dwarf Therapist GitHub repository for a new release or an updated memory layout file for the new game version.
Community forums and the repository’s Issues section will typically have discussion about the update’s status within a short time of a new Dwarf Fortress release.

Is Dwarf Therapist actively maintained for macOS and Linux?

Dwarf Therapist is an open-source community project. Maintenance activity varies over time depending on contributor availability. macOS and Linux support is community-driven and generally reliable, but response time after major Dwarf Fortress updates can vary.
The GitHub repository’s commit history and release page give the clearest picture of current maintenance activity for each platform.

Latest Post: