Installing DFHack¶
Requirements¶
DFHack supports all operating systems and platforms that Dwarf Fortress itself
supports, which at the moment is just 64-bit Windows. However, the Windows
build of DFHack works well under wine (or Proton, Steam’s fork of
wine) on other operating systems.
DFHack releases generally only support the version of Dwarf Fortress that they are named after. For example, DFHack 50.05 only supported DF 50.05. DFHack releases never support newer versions of DF – DFHack requires data about DF that is only possible to obtain after DF has been released. Occasionally, DFHack releases will be able to maintain support for older versions of DF - for example, DFHack 0.34.11-r5 supported both DF 0.34.11 and 0.34.10. For maximum stability, you should usually use the latest versions of both DF and DFHack.
Downloading DFHack¶
Stable builds of DFHack are available on Steam or from our GitHub. Either location will give you exactly the same package.
On Steam, note that DFHack is a separate app, not a DF Steam Workshop mod. You can run DF with DFHack by launching either the DFHack app or the original Dwarf Fortress app.
If you download from GitHub, downloads are available at the bottom of the release notes for each release, under a section named “Assets” (which you may have to expand). The name of the file indicates which DF version, platform, and architecture the build supports - the platform and architecture (64-bit or 32-bit) must match your build of DF. The DF version should also match your DF version - see above for details. For example:
dfhack-50.07-r1-Windows-64bit.zipsupports 64-bit DF on Windows
In between stable releases, we may create beta releases to test new features. These are available via the beta release channel on Steam or from our regular Github page as a pre-release tagged with a “beta” suffix.
Warning
Do not download the source code from GitHub, either from the releases page or by clicking “Download ZIP” on the repo homepage. This will give you an incomplete copy of the DFHack source code, which will not work as-is. (If you want to compile DFHack instead of using a pre-built release, see Building DFHack for instructions.)
Installing DFHack¶
If you are installing from Steam, this is handled for you automatically. The instructions here are for manual installs.
When you download DFHack, you will end up with a release archive
(a .zip file on Windows, or a .tar.bz2 file on other platforms). Your
operating system should have built-in utilities capable of extracting files from
these archives.
The release archives contain a hack folder where DFHack binary and system
data is stored, a stonesense folder that contains data specific to the
stonesense 3d renderer, and various libraries and executable files. To
install DFHack, copy all of the files from the DFHack archive into the root DF
folder, which should already include a data folder and a save folder,
among other things. Some redistributions of Dwarf Fortress may place DF in
another folder, so ensure that the hack folder ends up next to the data
folder, and you’ll be fine.
Note
On Windows, installing DFHack will overwrite SDL.dll. This is
intentional and necessary for DFHack to work, so be sure to choose to
overwrite SDL.dll if prompted. (If you are not prompted, you may be
installing DFHack in the wrong place.)
Uninstalling DFHack¶
Manually uninstalling DFHack essentially involves reversing what you did to
install. On Windows, replace SDL.dll with SDLreal.dll first. Then, you
can remove any files that were part of the DFHack archive. DFHack does not
currently maintain a list of these files, so if you want to completely remove
them, you should consult the DFHack archive that you installed for a full list.
Generally, any files left behind should not negatively affect DF.
On Steam, uninstalling DFHack will cleanly remove everything that was installed
with DFHack, including the SDL.dll file, which will render Dwarf
Fortress inoperative. In your Steam client, open the properties window for
Dwarf Fortress, select “Local Files”, and click on “Verify integrity of game
files…”. This will get Dwarf Fortress working properly again.
Note that Steam will leave behind the dfhack-config folder, which contains
all your personal DFHack-related settings and data. If you keep this folder,
all your settings will be restored when you reinstall DFHack later.
Upgrading DFHack¶
Again, if you have installed from Steam, your copy of DFHack will automatically be kept up to date. This section is for manual installers.
First, remove the hack and stonesense folders in their entirety. This
ensures that files that don’t exist in the latest version are properly removed
and don’t affect your new installation.
Then, extract the DFHack release archive into your Dwarf Fortress folder, overwriting any remaining top-level files (including SDL.dll).