Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/joncampbell123/dosbox-x/llms.txt

Use this file to discover all available pages before exploring further.

DOSBox-X is configured through an INI-style text file that controls everything from machine type and memory size to audio hardware and display output. Understanding how the config file works lets you fine-tune emulation for any DOS game, application, or operating system without touching a single menu.

​
Config file names and search order

DOSBox-X looks for its configuration file in the following locations, in order:
1

Current working directory

DOSBox-X first checks the directory from which it was launched for dosbox-x.conf. For backward compatibility it also accepts dosbox.conf in this location.
2

User config directory

If nothing is found in the current directory, DOSBox-X looks in the platform-specific user configuration folder (e.g. ~/.config/dosbox-x/ on Linux/macOS, or %APPDATA%\dosbox-x\ on Windows).
3

Program directory

Finally, DOSBox-X searches its own installation directory for a config file.
You can bypass the search order entirely by passing a config file explicitly on the command line: dosbox-x -conf myconfig.conf

​
File format

The config file uses a standard INI format. Section names appear in square brackets, and each option is written as a key = value pair on its own line. Any line beginning with # is treated as a comment and ignored by DOSBox-X. 
# This is a comment — DOSBox-X ignores it.

[dosbox]
machine   = svga_s3
memsize   = 16

[cpu]
core      = auto
cycles    = auto

[render]
aspect    = true
scaler    = normal2x

​
The [autoexec] section

The last special section, [autoexec], works like AUTOEXEC.BAT — every line is executed as a DOS command when DOSBox-X starts. Use it to mount drives, set environment variables, or launch a game automatically: 
[autoexec]
# Mount the host folder as drive C
mount c ~/dosgames
c:
dir

​
Generating a config file

User config (recommended)

Run dosbox-x -userconf to create a pre-populated config file in your user config directory that you can edit safely without affecting the installation.

GUI config tool

Open Main → Configuration Tool inside a running DOSBox-X session to edit settings through a graphical interface. Save with OK or write to disk with Save configuration.

Reference file

Copy dosbox-x.reference.conf from the installation directory as a starting point — it contains every option with inline comments explaining each one.

CONFIG command

Use the built-in CONFIG command from the DOSBox-X command prompt to read and write settings while the emulator is running (see below).

​
Specifying a config file at launch

# Use a specific config file
dosbox-x -conf myconfig.conf

# Layer multiple config files (later files override earlier ones)
dosbox-x -conf base.conf -conf game-override.conf

​
Runtime overrides with -set

You can override individual settings from the command line without editing any file: 
dosbox-x -set "dosbox memsize=32"
dosbox-x -set "cpu cycles=fixed 25000"
dosbox-x -set "render aspect=true"
The format is -set "section key=value". These overrides apply on top of any loaded config file.

​
The built-in CONFIG command

The CONFIG command lets you inspect and change settings while DOSBox-X is running. Changes made this way take effect immediately (where possible) but are lost when DOSBox-X exits unless you write them to disk. 
# Read the current value of a setting
CONFIG -get cpu cycles

# Change a setting at runtime
CONFIG -set cpu cycles fixed 25000
CONFIG -set render aspect true

# Write only the non-default options to a file
CONFIG -wc myconfig.conf

# Write ALL options (including advanced/hidden ones) to a file
CONFIG -all -wc fullconfig.conf
CONFIG -wc (short for -writeconf) writes only the options that differ from defaults or that DOSBox-X has loaded. Use CONFIG -all -wc to produce a complete reference file you can inspect and edit.

​
All configuration sections

DOSBox-X organises its settings into the following sections. Each section heading appears in square brackets in the config file.
SectionPurpose
[sdl]Window mode, output renderer, fullscreen, mouse, priority
[dosbox]Machine type, memory, language, captures directory
[render]Scalers, aspect ratio, frameskip, doublescan
[cpu]CPU core, type, cycle count, turbo mode
[keyboard]Keyboard controller type, PS/2 aux port
[ttf]TrueType font output settings (font, point size, word processor mode)
[mixer]Global audio sample rate, block size, silent mode
[midi]MIDI device, MT-32 emulation, FluidSynth soundfont
[sblaster]Sound Blaster type, base address, IRQ, DMA, OPL mode
[sblaster2]Second Sound Blaster instance
[gus]Gravis UltraSound emulation
[innova]Innovation SSI-2001 (SID chip) emulation
[imfc]IBM Music Feature Card emulation
[speaker]PC speaker, Tandy 3-voice, Disney Sound Source, PS/1 audio
[joystick]Joystick type, timed axes, autofire
[serial]Serial (COM) port devices (modem, nullmodem, file, directserial)
[parallel]Parallel (LPT) port devices (printer, file, reallpt)
[printer]Virtual dot-matrix printer output
[dos]XMS/EMS/UMB memory, keyboard layout, file handles, INT 33H mouse
[ipx]IPX network emulation over UDP/IP
[ne2000]NE2000 Ethernet emulation (pcap or slirp backend)
[ide, primary] … [ide, octernary]IDE controller instances (up to eight)
[fdc, primary]Floppy disk controller
[4dos]4DOS.INI settings when using 4DOS as the shell
[config]DOS CONFIG.SYS-equivalent (FILES, FCBS, SHELL, COUNTRY, etc.)
[autoexec]Startup DOS commands (like AUTOEXEC.BAT)

​
Minimal working configuration example

The following config is enough to run most DOS games with a Sound Blaster 16 and SVGA graphics. Save it as dosbox-x.conf and launch DOSBox-X from the same directory. 
# Minimal DOSBox-X configuration

[dosbox]
machine  = svga_s3
memsize  = 16

[cpu]
core     = auto
cputype  = auto
cycles   = auto

[render]
aspect   = true
scaler   = normal2x

[sblaster]
sbtype   = sb16
sbbase   = 220
irq      = 7
dma      = 1

[midi]
mididevice = default

[autoexec]
# Mount your DOS games folder as drive C:
mount c ~/dosgames
c:
Always start from dosbox-x.reference.conf when experimenting — it documents every available option with defaults. Never edit the reference file directly; copy it first.

Build docs developers (and LLMs) love

Get started for freeTalk to us