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 accepts a rich set of command-line options that control how the emulator starts, which configuration it loads, what program it runs, and how it behaves at runtime. Options may be prefixed with either a hyphen (-) or a forward slash (/), so -help and /help are equivalent. All options are case-insensitive.
Basic Usage dosbox-x [name] [options]
Where [name] is an optional path to a DOS executable (.com, .exe, or .bat) or a disk image to run immediately on launch. Any options listed below may accompany it.
On Windows builds, options can use either - or / as a prefix. On Linux and macOS, only - is guaranteed to work in all shells.
Configuration File Search Order When no -conf option is specified, DOSBox-X searches for a configuration file in the following order. The first file found is used:
Config file search locations (in priority order)
Current working directory — dosbox-x.conf
Current working directory — dosbox.conf
Directory of the DOSBox-X executable — dosbox-x.conf
Directory of the DOSBox-X executable — dosbox.conf
Platform resource directory (e.g., ~/.config/dosbox-x/) — dosbox-x.conf
User-level platform config directory — dosbox-x.conf
If none of these are found, DOSBox-X runs with built-in defaults. If a dosbox-x.conf (or dosbox.conf) file exists in the current working directory, it will override the user-level config file. This can cause unexpected behaviour when launching DOSBox-X from directories that contain game-specific configs.
Options Reference Help & Version
Display
Configuration
Startup & UI
Execution
Security & Host
Debugging
Display the help screen listing all available command-line options, then exit.
Print the DOSBox-X version string and copyright notice to stderr, then exit.
Show the extended help screen that lists advanced debugging-related options.
Launch DOSBox-X in fullscreen mode instead of a window.
Show the emulated CPU cycles count (displayed as FPS) in the window title bar.
Show the emulation speed relative to real-time in the title bar (e.g., 100% means real-time speed).
Do not show the DOSBox-X graphical user interface. Useful for scripted or headless use.
Do not show the menu bar at the top of the DOSBox-X window.
Enable standard and monochrome dual-screen mode. The <color> argument sets the monochrome display colour (e.g., green, amber, white).
Instruct DOSBox-X to ignore (not signal) Windows DPI awareness. Useful when running on high-DPI displays where automatic scaling causes problems. Windows only.
Load the specified configuration file instead of searching for one automatically. Can be specified multiple times to load several config files in order.
Open the active configuration file in the specified text editor (e.g., notepad, vim).
Create a user-level configuration file in the platform config directory if one does not already exist, then exit.
Print the path of the configuration file that would be loaded, then exit.
Erase the loaded config file (with -eraseconf) or erase the user-level config file and exit (with -resetconf).
-erasemapper, -resetmapper
Erase the loaded mapper file (with -erasemapper) or erase the user-level mapper file and exit (with -resetmapper).
Use DOSBox-X’s built-in default configuration settings, ignoring any configuration files on disk.
Use DOSBox-X’s built-in default key mappings, ignoring any mapper files on disk.
-set <section property=value>
Override a single configuration option from the command line, taking precedence over the config file. Surround the entire string in quotes if it contains spaces. dosbox-x -set "dosbox memsize=64" dosbox-x -set "render scaler=hq2x"
-lang <message file>, -langcp <message file>
Use a specific language/message file instead of the language= setting in the config file. -langcp behaves identically to -lang but additionally suppresses IME input for DBCS (double-byte character set) locales on Windows.
Start DOSBox-X emulating a specific machine type. Valid types include hercules, cga, ega, vgaonly, svga_s3, svga_et3000, svga_et4000, svga_paradise, vesa_nolfb, pc98, and others.
-startui, -startgui, -starttool
Launch DOSBox-X and immediately open the GUI configuration tool before the emulation begins.
Launch DOSBox-X and immediately open the key mapper editor.
Show a dialog to choose the working directory every time DOSBox-X starts.
Suppress the working directory prompt even if it would normally be shown.
Set the default working path for DOSBox-X to the specified directory.
Set the directory path used for save-state slots.
Open (or pass to a handler program) the captures folder or a capture file.
Open (or pass to a handler program) the saves folder or a save file.
Fast launch mode: skip the BIOS splash screen and the DOSBox-X welcome banner to reach the DOS prompt more quickly.
Execute this DOS command in addition to whatever is in the [autoexec] section of the config file. Surround the command in quotes to preserve spaces. dosbox-x -c "MOUNT C ~/games" -c "C:"
Provide command-line arguments to pass to [name] when it is executed. Useful when launching a specific executable and needing to forward flags to it.
When [name] is specified, run it before the [autoexec] section of the config file rather than after.
Do not execute the [config] (CONFIG.SYS) section of the config file during boot.
Do not execute the [autoexec] section of the config file.
Automatically exit DOSBox-X once the [autoexec] section finishes executing.
Run DOSBox-X silently (suppress audio and visible output) and exit automatically after the [autoexec] section completes.
Force DOSBox-X to terminate after n seconds of wall-clock time. Useful for automated testing.
Specify the socket number used for null-modem serial emulation.
Enable secure mode. In this mode, drive mounting, the mapper editor, and config write operations are disabled. Useful in kiosk or shared environments.
Enable the ability to launch host (native OS) programs from inside DOSBox-X via the START command, and enable Long Filename (LFN) support.
Disable the check that warns when NumLock is active at startup. Windows builds only.
Force the emulated DOS date to stay synchronised with the host system date.
These options are shown by running dosbox-x -helpdebug. They are intended for developers and advanced users.
Set all internal logging levels to debug verbosity.
Log early initialisation messages (implies -console on Windows).
Log every SDL key event to the console. Useful for diagnosing keyboard mapping problems.
Break into the built-in debugger immediately at startup, before the BIOS runs.
Show the logging console window. Windows builds only.
Suppress the logging console window. Windows debug builds only.
Write all CON (console) output to a log file.
Log all INT 21h DOS API calls at debug level.
Log all file I/O operations made through INT 21h at debug level.
Disable all logging to the log file entirely.
Run the DOSBox-X internal unit tests and report results, then exit.
Print emulator time alongside SDL_GetTicks() values. Low-level timing diagnostic.
Force the render scaler system to behave as if GFX_HARDWARE is active.
Quick-Reference Table Option Description -helpShow help screen -versionShow version info -fullscreenStart in fullscreen -conf <file>Load config file -set <s p=v>Override a config value -c <cmd>Run extra DOS command -exitExit after autoexec -fastlaunchSkip BIOS/welcome screen -securemodeDisable mounting & mapper -machine <type>Select machine type -lang <file>Use message/language file -startuiOpen GUI config tool -startmapperOpen key mapper -noautoexecSkip autoexec section -silentRun silently and exit -time-limit <n>Kill after n seconds -debugEnable debug logging
You can chain multiple -c options on a single command line to execute a sequence of DOS commands at startup. For example: dosbox-x -c "MOUNT C ~/dosgames" -c "C:" -c "CD MYAPP" -c "MYAPP.EXE" -exit