Compiling

This page contains help on compiling NetHack 5.0.0, either the officially released version (5.0.0) or the version from the development sources (as of 2026 July 4). Compiling is necessary if you want to try out the Dev Team's latest changes when they haven't released a compiled version yet, or if you want to apply a patch, e.g. from the bilious database or make changes of your own.

Information about compiling NetHack 3.6 can still be found in an old version of this article, q.v.

Information about compiling NetHack 3.4.3 can still be found in an old version of this article, q.v..

Obtaining the officially released sources

The official released NetHack source can be found here: https://nethack.org/v500/downloads.html

Once you have obtained the tarball gzip archive, you will need to extract it, either using standard tools (tar -xvf nethack-500-src.tgz) or some other archive extractor that can handle the tar and gzip formats.

Note that if you use a graphical archive extractor like 7zip, you may have to extract twice: once to decompress the gzip and obtain the plain tar file, and a second time to extract the actual contents. Extracted subdirectory (a.k.a., a "folder") is called 'NetHack-5.0.0' and it contains 2026 May 2 released source.

Obtaining the development sources

The development source repository is available at https://git.code.sf.net/p/nethack/NetHack

If you have git installed, you can retrieve a copy of the repository using either of the following commands:

git clone https://github.com/NetHack/NetHack

alternatively:

git clone https://git.code.sf.net/p/nethack/NetHack

(It doesn't matter which repository you use; they are both mirror of the public portion of the Dev Team's repository.)

This will create a subdirectory (a.k.a., a "folder") called 'NetHack', in the current directory, and the new subdirectory, 'NetHack', will be a git repository, containing a working copy of the latest public development source for what will eventually become NetHack 5.0.1.

Preparing to compile

Gathering build tools

In order to build NetHack, you will neet at minimum the following tools:

• a C compiler (typically 'gcc' or 'clang')
• 'make' (preferably GNU make)
• Lua 5.5.0 (or older version) is needed, but NetHack is shipped with it, so having a system package is not necessary.
• NetHack 5.0.0 has replaced 'flex' and 'bison' (or some other suitable lex/yacc implementation) with Lua intrepeter you will still need these if you are compiling older version.
• Common libraries (including development headers); these should be included if you have a complete working build environment (e.g., if you have installed build-essential on Debian-derived systems, you should have them). There is no complete list of all the libraries that are required, but I believe the list includes standard POSIX regular expression libraries, termcap/terminfo, and of course the standard C library. Beyond that, I'm not sure.
• Any libraries (including development headers) needed for the specific ports you wish to build; if this is the first time you are building NetHack, it is recommended that you start by building the default UNIX 'tty' first, as it is the easiest and has no additional requirements of its own beyond the ones that all the windowing require.

The DevTeam Cross-compiling Initiative

Note that you will need copies of all these on the platform for which you are building NetHack. The NetHack 5.0 build process differs from the build process of previous versions in some important ways. Those differences make it possible to use a cross-compiler running on one platform (the "host" platform of the build) to produce a binary NetHack package that can execute on an entirely different platform. However in this article we assume compiling on the platform you run the game.

Selecting a Hints file

The new build system (introduced in NetHack 3.6.0) is based on "hints files", which inform the rest of the build system about various things which might differ from one system to another, and which you might wish to customize when building, even if you are making no changes to the actual game. Things like which directory to install the game's binaries into, which directory to use for storing the game data, which flags to pass to the compiler, and even basic facts like what the compiler on your system is called, are all specified in the hints file. A hints file is simply a plain text file, formatted like a shell script, that contains hints for the NetHack build system, in the form of setting variables.

You can find a collection of existing hints files in the sys/unix/hints/ directory. You may find that one of them is closer to what you want than others. For example, the 'linux.500' hints file is designed for a single-user compile in home/nethacker/games/NetHack/playground install (e.g. SOURCE install); whereas, the 'unix' and 'linux-minimal' hints file are designed for a traditional system-wide install in /usr/lib/games (for multiple players). Look through the existing hints files and see if you can find one that is a close fit for your needs and platform software.

Modifying a Hints file

If you need to combine or modify a hints file, here are some useful things to know:

• Lines starting with # are comments. You can thus prepend # to an existing line to comment it out, rendering it ineffective but leaving it there for reference.
• There are four main directories that need to be specified: 'HACKDIR', 'SHELLDIR', 'INSTDIR', and 'VARDIR'. These are often based on a 'PREFIX' directory, which is not itself used directly for anything, but the others are typically located inside of it. Biggest change in version 5.0.0 single-user install hints file sys/unix/hints/linux.500' is that these directories are NOT set in the main hints file, but in separate sys/unix/hints/include/dirs-perms.500 instead.

Make sure that you follow the comments about setting HACKDIR -- the installation process will wipe out the contents of the directory you point it at, under the assumption that it's debris from an old version of NetHack. If this is not the case, you'll want to install somewhere else, or comment out the rm (recursive remove) under the install target.

• The CHOWN and CHGRP variables should contain the commands used to change ownership and group-ownership of files, respectively. Setting it to a command that doesn't do anything (such as 'yes' or 'true', as the stock 'unix' and'linux-minimal' hints files do) will result in permissions not being changed, which is typically not what you want except possibly for a single-user install. If you are modifying the 'linux-minimal' hints file to build on a Linux system, you will probably want to change these lines.
• sys/unix/hints/include/multiw-1.500 hints file controls which window port(s) you will build (also see make all variables down below) If this is your first time compiling NetHack, it is recommended to start with the TTY port, which is easiest to build successfully.
• Very few Compile-time options are still left unconditional. Almost all config-options can be changed in the Sysconf during runtime (Sysconfig is compiled by default).

Three examples of Compiling Flags that can only be set during compilation (Nethacksources control):

#NHCFLAGS+=-DMSGHANDLER

Execute an external program whenever a new message-window message is shown. The program to execute is given in environment variable NETHACK_MSGHANDLER. Important for Accessibility installs. Not enabled by default.

#NHCFLAGS+=-DSCORE_ON_BOTL

Enable the showscore-option on statusline. Not enabled by default.

#NHCFLAGS+=-DNO_CHRONICLE 

Disable the ingame extended #chronicle command (lists significant achievements (complete Sokoban, perform invocation, etc) Enabled by default.

Running the build setup script

Once you have selected and possibly modified a hints file, you are almost ready to run the setup script.

Then on most platforms, setup is done with the following commands:

"$Top" is the top level source directory (the one with README in it).

cd $Top/sys/YOUR_PLATFORM

sh setup.sh hints/NAME_OF_HINTS_FILE

On non-Unix platforms, the setup process may be slightly different. See the documentation for your platform. The setup script should copy the needed build-system files (e.g., makefiles) into place and modify them as needed.

Windows

The following information pertains to an upcoming version (NetHack 3.7.0). If this version is now released, please verify that the information below is still accurate, then update the page to incorporate it.

Nethack 3.7 has good support for building, running, and debugging in Visual Studio 2017, 2019, and 2022, including a working solution file. Tools such as MinGW and GnuWin32 are not required. See sys\windows\Install.windows for instructions.

For Nethack 3.6 on Windows, it's a good idea to follow the instructions inside sys\winnt\Install.nt. The following assumes that you have your compiler and coreutils from projects such as MinGW and GnuWin32.

• Navigate to sys\winnt and run nhsetup.bat.

• Navigate to src and edit Makefile.gcc.

• Inside the Makefile, you're going to want to edit or check the following things:
  • Do you want the outputted binary to belong in ..\binary, or somewhere else?
  • Are you compiling for a specific architecture (x86 or x64)? If so, edit TARGET_CPU.
  • Do you want Curses window port support? If so, uncomment ADD_CURSES=Y and make sure that you've cloned the PDCurses repository from https://github.com/wmcbrine/PDCurses.
  • TODO: (Test this, I only wanted the terminal interface) Do you want Qt support? You're going to want to change this option and specify the location of the Qt directory.
  • On Line 484, are the compiler macros set up correctly? Mine were not, as Chocolatey links the compilers to standard gcc filenames instead of mingw32-gcc.exe. Comment out the #ifndef directive and specify the compilers.

• Make with your make program. For me, the invocation was mingw32-make -f Makefile.gcc install. Note that if you don't specify the -f Makefile.gcc option, you'll get an error, as the standard Makefile is for Visual Studio's nmake program.

Compiling

Fetch Lua

(If you use the same terminal emulator you used to give the ./setup.sh command)

$Top is the top level source directory (the one with README in it).

Return from hints subdirectory to with this change directory $Top:

cd ../..

Download the Lua interpreter (this will create a lib subdirectory to your $Top).

make fetch-lua

The 'make fetch-Lua' step really only needs to be done one time unless your sources get refreshed, or the lib folder and its contents get removed.

Make all

At this point, you might be able to just run the

make all

command and get a working build.

NetHack can support multiple user interfaces within the same binary on many
platforms. The various interface options can be specified by defining specific
variables, either on the make command line, or by setting environment variables
prior to the "make all" and "make install" steps. If you don't specify any
WANT_WIN_* customization, the build will only include traditional tty support.

As an example, to build a binary with tty + curses + X11 support, you can use
the following build command:
   make WANT_WIN_TTY=1 WANT_WIN_CURSES=1 WANT_WIN_X11=1 all
   make WANT_WIN_TTY=1 WANT_WIN_CURSES=1 WANT_WIN_X11=1 install

To build a binary with tty + curses + X11 + Qt support (that is, all the
interfaces that are available for unix), you can use the following shorthand
build command:
   make WANT_WIN_ALL=1 all
   make WANT_WIN_ALL=1 install

Alternatively, you can set the variables in the environment first, prior
to issuing your make commands:
   export WANT_WIN_TTY=1
   export WANT_WIN_X11=1
   make all
   make install

That example above will result in a build with support for tty + X11.

Installing

If the build goes well, you can (as root/superuser if necessary, or with sudo) use the 'make install' command to install your newly compiled NetHack (with same variables you used for 'make all' above).

$Top" is the top level source directory (the one with README in it).

make install

If you encounter errors during complaining, giving 'make spotless' command will clear the build, and you can start again from beginning. If you want to make a new build, and have not changed monster or level files, 'make update' command can be given instead of 'make all'.

Creating the system config file for runtime options

Linux.500 hints file will copy a sample Sysconf file to HACKDIR you spesified, this might be a problem if you are compiling other hints file (or an older version).

When you try to run your new build, it will complain that there is no syscf file and refuse to do anything until you create that file. The syscf file is allowed to be empty; it just has to exist. Simply create an empty file named sysconf in your HACKDIR and nethack will run normally.

Depending on which hints file you used, some permissions may need to be changed before the game can be run as a regular user.

Good Luck & Happy Compiling!