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.

The [dosbox] section is the heart of DOSBox-X configuration, controlling the emulated hardware profile, system memory, startup presentation, save-state management, and how the emulator interacts with the host environment. Options here determine everything from which DOS machine is being replicated all the way down to whether auto-saving is active and how the A20 address gate is emulated. Most settings require a restart to take effect.

​
Startup & Presentation

​
language
string
default:""
Path to a language file for DOSBox-X’s UI strings. Files may be encoded as UTF-8 or with a DOS code page. Leave blank to use the built-in English strings.
​
beep duration
integer
default:"0"
Duration in milliseconds of the beep sound produced when DOS or INT 10h receives a BEL (ASCII 7) character. Set to 0 to use the system default duration.
​
title
string
default:""
Additional text placed in the DOSBox-X window title bar, supplementing the information shown via showbasic and showdetails in [sdl].
​
logo text
string
default:""
Text displayed at the bottom of the screen during the startup logo animation. Text wraps automatically; use \n to force a line break.
Base file path of PNG images to display instead of the default DOSBox-X logo at startup. For example, logo=subdir/mylogo with machine=vgaonly will look for subdir/mylogo224x224.png.
When set, DOSBox-X skips the 1-second pause during the BIOS logo screen, booting faster.
​
startbanner
boolean
default:"true"
When set (the default), DOSBox-X displays the welcome banner in the DOS shell on startup. Disable to skip directly to the DOS prompt.
​
bannercolortheme
string
default:"default"
Background color theme for the startup welcome banner. Possible values: default, black, red, green, yellow, blue, magenta, cyan, white.
​
configuration tool theme
string
default:""
Visual theme for the built-in Configuration Tool dialog. If left blank, DOSBox-X follows the host operating system’s dark/light mode setting. Available named themes include: Windows Default, Arizona, Black Leather Jacket, Bordeaux, Cinnamon, Designer, Emerald City, Fluorescent, HotDog Stand, LCD Default Screen Settings, LCD Reversed - Dark, LCD Reversed - Light, Mahogany, Monochrome, Ocean, Pastel, Patchwork, Plasma Power Saver, Rugby, The Blues, Tweed, Valentine, Wingtips.

​
Host Integration

​
dpi aware
string
default:"auto"
Informs the host OS that DOSBox-X is DPI-aware. Without this, Windows Vista and later may upscale the window on high-DPI monitors, producing a blurry result. Possible values: true, false, 1, 0, auto.
​
quit warning
string
default:"auto"
Controls whether a warning dialog appears when closing the DOSBox-X window. Possible values:
  • auto — warn if a DOS program, game, or guest OS is running
  • autofile — warn if there are open file handles or a guest OS is running
  • true / 1 — always warn
  • false / 0 — never warn
​
working directory option
string
default:"default"
Determines DOSBox-X’s working directory when it launches. Possible values:
  • autoprompt — auto-decide whether to prompt for a directory
  • config — use the primary config file’s directory
  • custom — use the path from working directory default
  • default — like autoprompt, but asks whether to save the chosen folder
  • force — like custom, and overrides the -defaultdir command-line flag
  • noprompt — use the current directory and never prompt
  • program — use the DOSBox-X executable’s directory
  • prompt — always prompt the user at startup
  • userconfig — use the DOSBox-X user configuration directory
​
working directory default
string
default:""
The directory used when working directory option=custom or force. For prompt mode, this becomes the initially-selected folder in the folder-picker dialog.
​
show advanced options
boolean
default:"false"
When set, the Configuration Tool displays all configuration options (including advanced ones) by default, rather than hiding rarely-used settings.
​
resolve config path
string
default:"true"
If set to true, DOSBox-X resolves environment variables and paths found in the config file (excluding [autoexec]). Supported variable syntaxes: %VAR% (DOS/Windows) and ${VAR} (Linux/macOS), as well as tilde (~) expansion on Unix. Possible values: true, false, dosvar, tilde, 1, 0.
​
hostkey
string
default:"mapper"
Specifies the host key used for DOSBox-X keyboard shortcuts such as toggling fullscreen. Using mapper means the key defined in the mapper file (default: F11 on Windows, F12 on other platforms) is used. You can also select this from Main → Select host key. Possible values: ctrlalt, ctrlshift, altshift, mapper.
​
mapper send key
string
default:"ctrlaltdel"
Selects which key combination the mapper’s SendKey function sends to the guest. Possible values: winlogo, winmenu, alttab, ctrlesc, ctrlbreak, ctrlaltdel.
​
ime
string
default:"auto"
Enables Input Method Editor (IME) support for inputting CJK characters on Windows and Linux. With auto, IME is only activated if DOSBox-X starts with a Chinese, Japanese, or Korean code page. Possible values: true, false, 1, 0, auto.
​
synchronize time
boolean
default:"false"
When enabled, DOSBox-X automatically synchronizes the emulated system clock with the host clock, unless the user manually changes the date or time inside DOS.

​
Machine Type

​
machine
string
default:"svga_s3"
The type of PC hardware DOSBox-X emulates. This affects available video modes, sound capabilities, and BIOS behavior. Common values:Text / Monochrome: mda, hercules, hercules_plus, hercules_incolor, hercules_colorCGA variants: cga, cga_mono, cga_rgb, cga_composite, cga_composite2Other early systems: tandy, pcjr, pcjr_composite, pcjr_composite2, amstradEGA / MCGA: ega, ega200, jega, mcgaVGA / SVGA: vgaonly, svga_s3 (default), svga_s386c928, svga_s3vision864, svga_s3vision868, svga_s3vision964, svga_s3vision968, svga_s3trio32, svga_s3trio64, svga_s3trio64v+, svga_s3virge, svga_s3virgevxET / Paradise / ATI SVGA: svga_et3000, svga_et4000, svga_paradise, svga_ati_egavgawonder, svga_ati_vgawonder, svga_ati_vgawonderplus, svga_ati_vgawonderxl, svga_ati_vgawonderxl24, svga_ati_mach8, svga_ati_mach32, svga_ati_mach64VESA modes: vesa_nolfb, vesa_oldvbe, vesa_oldvbe10, vesa_vbe3NEC PC-98: pc98, pc9801, pc9821DOSBox compatibility: svga_dosbox, svga_dosbox_vbe2FM-TOWNS: fm_towns

​
Memory

​
memsize
integer
default:"16"
Amount of RAM available to the emulated DOS system, in megabytes. The default of 16 MB works best for most games. Some 286 protected-mode software (e.g. Windows 3.0 Standard Mode) may crash with more than 15 MB. The maximum is up to 1,048,576 (1 TB) with appropriate CPU type and memalias settings; values of 4 GB or more require a memory file. See the DOSBox-X console log for effective limits.
​
memory file
string
default:""
If specified, guest memory is backed by a memory-mapped file on disk rather than host RAM. Useful when memsize is very large. The file will be created automatically if it does not exist and requires no special formatting.
​
a20
string
default:"mask"
A20 gate emulation mode, controlling how the CPU accesses the 1 MB memory boundary. Possible values:
  • fast — emulate by remapping the first 64 KB at the 1 MB boundary (fast; mainline DOSBox behavior)
  • mask — emulate by masking memory I/O addresses (accurate; default)
  • off — lock A20 gate off; software cannot enable it
  • on — lock A20 gate on; software cannot disable it
  • off_fake — gate locked off, but the toggle bit still responds (tests HMA detection)
  • on_fake — gate locked on, but the toggle bit still responds
This can also be changed at runtime using the built-in A20GATE command.
​
nocachedir
boolean
default:"false"
When set, all MOUNT commands will default to -nocachedir, disabling directory caching. Useful if the host filesystem changes frequently outside of DOSBox-X.
​
freesizecap
string
default:"cap"
Controls how MOUNT -freesize reports free disk space. Possible values:
  • cap / true — the specified free size is only applied if actual free space exceeds it
  • relative — the free size value is applied relative to actual free space
  • fixed / false — the specified value is always reported regardless of actual space
​
convertdrivefat
boolean
default:"true"
When set, DOSBox-X automatically converts mounted non-FAT drives (such as host filesystem mounts) to FAT format for compatibility with guest operating systems that require FAT.

​
Save States

​
autosave
string
default:""
Enable and configure the automatic save-state feature. Format: <seconds> [slot-range] [PROGRAM:slot-or-range] ...
  • autosave=10 — save every 10 seconds to the default slot
  • autosave=10 11-20 — save every 10 seconds, cycling through slots 11–20
  • autosave=10 11-20 EDIT:21-30 — also use slots 21–30 specifically for EDIT.COM
  • Prefix the interval with - to define the configuration without activating it at startup
Up to 9 program-specific slot ranges may be specified.
​
saveslot
integer
default:"1"
The default save-state slot number used when saving or loading states. Valid range is 1 to 100.
​
savefile
string
default:""
Path to a specific save-state file. When specified, this file is used instead of the numbered slot selected by saveslot.
​
saveremark
boolean
default:"true"
When enabled, DOSBox-X prompts you to enter a text remark (description) each time you save a state, making it easier to identify saves later.
​
forceloadstate
boolean
default:"false"
When enabled, DOSBox-X will load a saved state even if it detects a mismatch in DOSBox-X version, machine type, program name, or memory size. Use with caution as mismatched states may cause instability.

​
Captures

​
captures
string
default:"capture"
Directory path where DOSBox-X saves captured files such as WAV audio recordings, MIDI recordings, and screenshots.

Build docs developers (and LLMs) love

Get started for freeTalk to us