Building DOSBox-X from Source Code (All Platforms)

DOSBox-X can be compiled from source on all major platforms. The build system supports both SDL 1.2 (included in-tree with heavy modifications) and SDL 2.x. In addition to pre-built releases and nightly development builds, building from source gives you full control over feature flags, SDL version, and target platform.

The SDL 1.x library shipped in-tree has been heavily modified from the upstream SDL 1.2 sources — it is not compatible with a stock SDL 1.2 installation. Always use the in-tree version for SDL1 builds.

Prerequisites

The build requires a C++ compiler capable of at least the C++11 standard (GCC, Clang, or MSVC 2017+). New contributions should target C++14 compatibility per the project coding guidelines.

Required (all platforms)

C++11-capable compiler minimum (GCC, Clang, MSVC 2017+)
SDL 1.2 (in-tree) or SDL 2.x
make, autoconf, automake
nasm (for x86 assembly cores)
pkg-config

Optional libraries

libpng — screenshot support
libfluidsynth — SoundFont/MIDI synthesis
libfreetype — TrueType font (TTF) output
libslirp / libpcap — NE2000 networking backends
ffmpeg libs — video capture support
ncurses / pdcurses — built-in debugger

Platform Build Instructions

Visual Studio 2017, 2019, and 2022 are all supported. The resulting executables target Windows Vista (32-bit or 64-bit) and higher.Steps:

Open the solution file

Open ./vs/dosbox-x.sln in Visual Studio 2017, 2019, or 2022.

Select platform and SDL version

Choose your target platform (Win32 or x64, ARM or ARM64) and select either the SDL1 or SDL2 build configuration from the Configuration Manager.

Set the platform toolset

The default toolset is v142 (VS 2019). Change to v141 (VS 2017) or v143 (VS 2022) to match your installed build tools.

VS 2017 requires you to explicitly set WindowsTargetPlatformVersion, for example 10.0.22000.0. ARM builds require SDK version 10.0.22621.0 or earlier.

Install the DirectX 2010 SDK (optional)

Direct3D 9 output support requires the DirectX SDK (June 2010). This is optional; other output modes work without it.

Build

Select Build → Build Solution. SDL, FreeType, libpng, zlib, pdcurses, and FluidSynth libraries are already bundled — no extra installation is needed.

Windows XP target:To produce an executable that runs on Windows XP, change the platform toolset to v141, build normally, then patch the PE header:

./contrib/windows/installer/PatchPE.exe path-to-your-exe-file/dosbox-x.exe

The slirp networking backend is only available in MinGW builds. Visual Studio builds do not support libslirp. Use the pcap backend or MinGW if you need slirp-based NE2000 networking.

MinGW builds support the slirp networking backend and are used for the official release and nightly binaries. Use MSYS2 for the easiest setup.

Install MSYS2 and dependencies

Open the correct MSYS2 shell for your target architecture and install the required packages.

32-bit (mingw32)
64-bit (mingw64)
64-bit (UCRT64)

pacman -S git make mingw-w64-i686-toolchain mingw-w64-i686-libslirp \
  mingw-w64-i686-libtool mingw-w64-i686-nasm autoconf automake \
  mingw-w64-i686-ncurses

pacman -S git make mingw-w64-x86_64-toolchain mingw-w64-x86_64-libslirp \
  mingw-w64-x86_64-libtool mingw-w64-x86_64-nasm autoconf automake \
  mingw-w64-x86_64-ncurses

pacman -S git make mingw-w64-ucrt-x86_64-toolchain \
  mingw-w64-ucrt-x86_64-libtool mingw-w64-ucrt-x86_64-nasm \
  autoconf automake mingw-w64-ucrt-x86_64-libslirp

Clone the repository

git clone https://github.com/joncampbell123/dosbox-x.git
cd dosbox-x

Build (Windows 7+)

Choose SDL1 or SDL2:

# SDL1 build
./build-mingw

# SDL2 build
./build-mingw-sdl2

Windows XP / Vista (lowend build):Use the 32-bit lowend MinGW toolchain for XP compatibility. Download the toolchain from the link in the repository and overwrite the MSYS2 MinGW32 environment with it.

# SDL1
./build-mingw-lowend

# SDL2
./build-mingw-lowend-sdl2

Windows 9x / NT4 (32-bit SDL1 only):

./build-mingw-lowend9x

Lowend and 9x builds must not be compiled with MinGW-w64. Use the original MinGW (32-bit) toolchain only — MinGW-w64 introduces runtime dependencies that Windows XP, Vista, and 9x/NT4 do not support.

Ubuntu 20.04 and later (and compatible Debian-based distros) are well-tested. An equivalent build-debug-sdl2 script is available for SDL2.

Install dependencies

sudo apt install automake gcc g++ make libncurses-dev nasm \
  libsdl-net1.2-dev libsdl2-net-dev libpcap-dev libslirp-dev \
  fluidsynth libfluidsynth-dev libavdevice58 libavformat-dev \
  libavcodec-dev libavcodec-extra libavcodec-extra58 libswscale-dev \
  libfreetype-dev libxkbfile-dev libxrandr-dev

Clone the repository

git clone https://github.com/joncampbell123/dosbox-x.git
cd dosbox-x

Build and install

# SDL1 build
./build-debug
sudo make install

# SDL2 build (alternative)
./build-debug-sdl2
sudo make install

For Raspberry Pi, add libtool autogen to the apt command above. The ./build-debug and ./build-debug-sdl2 scripts work the same way. If you experience audio issues, prefer the SDL2 build.

Fedora Workstation and RHEL/CentOS (with EPEL) are supported. Video recording via FFmpeg requires the optional rpmfusion-free repository.

Install development tools and libraries

sudo dnf group install "C Development Tools and Libraries"
sudo dnf install SDL_net-devel SDL2_net-devel libxkbfile-devel \
  ncurses-devel libpcap-devel libslirp-devel libpng-devel \
  fluidsynth-devel freetype-devel nasm

For video recording support, also install ffmpeg-devel from rpmfusion-free.

Clone the repository

git clone https://github.com/joncampbell123/dosbox-x.git
cd dosbox-x

Build and install

./build-debug
sudo make install

# Or SDL2:
./build-debug-sdl2
sudo make install

Building an RPM package:

sudo dnf group install "RPM Development Tools"
./make-rpm.sh

The resulting RPM is placed in the releases/ directory.

macOS High Sierra (10.13) and later are supported, including Intel, Apple Silicon, and Universal Binary builds. The compiler is LLVM/Clang from Xcode; the build system uses GNU autotools installed via Homebrew or MacPorts.

Install Xcode command-line tools

xcode-select --install

Install dependencies via Homebrew or MacPorts

Homebrew
MacPorts

brew install autoconf automake nasm glfw glew fluid-synth \
  libslirp libpcap pkg-config sdl2_net

sudo port install autoconf automake nasm glfw glew fluidsynth \
  libslirp libpcap pkgconfig libsdl2_net

MacPorts is recommended when targeting older macOS versions.

Clone the repository

git clone https://github.com/joncampbell123/dosbox-x.git
cd dosbox-x

Build

# SDL1, native architecture
./build-macos

# SDL2, native architecture
./build-macos-sdl2

# Universal Binary (Apple Silicon host only)
./build-macos universal
./build-macos-sdl2 universal

(Optional) Create an App Bundle

make dosbox-x.app

Universal Binary builds require a host machine with an Apple Silicon CPU and parallel Homebrew installations running natively and under Rosetta 2. They cannot be built on Intel Macs.

Targeting macOS Sierra (10.12) and older (experimental):

sudo port install autoconf automake nasm glfw glew fluidsynth \
  libslirp libpcap pkgconfig libsdl2_net libpng zlib

./build-macosold        # SDL1
./build-macosold-sdl2   # SDL2

DOSBox-X can be compiled to run natively in a real MS-DOS 5.0+ environment using the HX DOS Extender. This requires the original 32-bit MinGW toolchain (not MinGW-w64).

Set up the MinGW toolchain

Download the HX-DOS build environment from the link in the repository (build-scripts/mingw/lowend-bin/) and install it into your MSYS2 MinGW32 environment.See hxdos.yml for the exact steps used in the official CI builds.

Build (SDL1, 32-bit only)

./build-mingw-hx-dos

HX-DOS builds must not use MinGW-w64. The HX DOS Extender does not support the additional runtime dependencies introduced by MinGW-w64.

Build Script Reference

The repository ships several convenience build scripts. All scripts invoke the configure step with preset flags appropriate for the target.

Script	Description
`./build`	Standard build
`./build-debug`	Debug build with SDL1 (Linux/macOS)
`./build-debug-sdl2`	Debug build with SDL2 (Linux/macOS)
`./build-sdl2`	SDL2 release build
`./build-mingw`	MinGW Windows 7+ SDL1 build
`./build-mingw-sdl2`	MinGW Windows 7+ SDL2 build
`./build-mingw-lowend`	MinGW XP-compatible SDL1 build
`./build-mingw-lowend-sdl2`	MinGW XP-compatible SDL2 build
`./build-mingw-lowend9x`	MinGW Windows 9x/NT4 SDL1 build
`./build-mingw-hx-dos`	DOS with HX Extender (SDL1, 32-bit)
`./build-macos`	macOS SDL1 build
`./build-macos-sdl2`	macOS SDL2 build
`./build-macosold`	macOS Sierra and older (experimental)

Configure Script Options

The configure script accepts flags to enable or disable specific features. Pass them after the script name, for example:

./build-debug --enable-debug=heavy --disable-opengl

Key options include:

Flag	Effect
`--enable-sdl`	Use SDL 1.x
`--enable-sdl2`	Use SDL 2.x
`--enable-debug[=heavy]`	Enable the built-in debugger (use `heavy` for extra detail)
`--enable-d3d9`	Enable Direct3D 9 output
`--disable-opengl`	Disable OpenGL output
`--disable-avcodec`	Disable FFmpeg video capture
`--disable-freetype`	Disable TrueType font output
`--disable-mt32`	Disable MT-32 emulation
`--disable-dynamic-x86`	Disable the x86/x64 dynamic CPU core
`--disable-dynrec`	Disable the recompiling CPU core
`--disable-fpu`	Disable FPU emulation
`--enable-hx-dos`	Enable HX-DOS target

Use ./configure --help inside the source tree for the full list of flags. To get verbose build output, run make V=1 after configuring.

Library Reference

Library	Required	Purpose
SDL 1.2 (in-tree)	One of the two SDL options	Core window/input/audio (modified)
SDL 2.x (in-tree)	One of the two SDL options	Core window/input/audio
zlib (in-tree)	Yes	Save states, CHD support, libpng
libpng (in-tree, optional)	No	Screenshots
FreeType (in-tree, optional)	No	TTF output, printing
SDL_Net (in-tree, optional)	No	Modem/IPX networking
SDL_Sound (in-tree, optional)	No	Compressed CD audio (MP3/OGG/FLAC)
ncurses / pdcurses	No	Built-in debugger
FluidSynth	No	SoundFont MIDI synthesis
libpcap / Npcap	No	NE2000 pcap networking backend
libslirp	No	NE2000 slirp networking backend
FFmpeg (avcodec etc.)	No	Video capture
ALSA headers	No	ALSA MIDI on Linux

Command-Line Options

DOS Commands

Configuration Reference

Building & Contributing

Building DOSBox-X from Source Code (All Platforms)

Prerequisites

Required (all platforms)

Optional libraries

Platform Build Instructions

Build Script Reference

Configure Script Options

Library Reference

Build docs developers (and LLMs) love

Command-Line Options

DOS Commands

Configuration Reference

Building & Contributing

Documentation Index

​Prerequisites

Required (all platforms)

Optional libraries

​Platform Build Instructions

​Build Script Reference

​Configure Script Options

​Library Reference

Build docs developers (and LLMs) love

Prerequisites

Platform Build Instructions

Build Script Reference

Configure Script Options

Library Reference