dosbox - Man Page

DOSBox Staging, x86/DOS emulator, a modern continuation of DOSBox


dosbox [--fullscreen] [--startmapper] [--noautoexec] [--securemode] [--conf <configfile>] [--lang <langfile>] [--machine <type>] [--socket <num>] [-c <command>] [--exit] [PATH]

dosbox --help

dosbox --version

dosbox --printconf

dosbox --editconf

dosbox --eraseconf

dosbox --noprimaryconf

dosbox --nolocalconf

dosbox --set <property>=<value>

dosbox --working-dir <path>

dosbox --list-countries

dosbox --list-glshaders

dosbox --erasemapper


This manual page briefly documents DOSBox Staging, a modern continuation of DOSBox.

If PATH is a directory, it's mounted as C:.
If PATH is a bootable disk image (.IMA/.IMG), it's booted.
If PATH is a CD-ROM disc image (.CUE/.ISO), it's mounted as D:.
If PATH is a DOS executable (.BAT/.COM/.EXE), it's parent path is mounted as C: and the executable is run. When the executable exits, DOSBox Staging quits.

For an introduction, type INTRO inside DOSBox Staging.

The document will refer to DOSBox Staging as dosbox from now on for readability.


Legacy single dash abbrevations still work for backwards compatibility.

--conf <config_file>     Start with the options specified in <config_file>.

Multiple configuration files can be specified.
                        Example: --conf conf1.conf --conf conf2.conf

--printconf              Print the location of the primary configuration file.

--editconf               Open the primary configuration file in a text editor.

--eraseconf              Delete the primary configuration file.

--noprimaryconf          Don't load or create the primary configuration file.

--nolocalconf            Don't load the local 'dosbox.conf' configuration file

if present in the current working directory.

--set <setting>=<value>  Set a configuration setting. Multiple configuration
                        settings can be specified. Example:
                        --set mididevice=fluidsynth --set soundfont=mysoundfont.sf2

--working-dir <path>     Set working directory to <path>. DOSBox will act as if

started from this directory.

--list-countries         List all supported countries with their numeric codes.

Codes are to be used in the 'country' config setting.

--list-glshaders         List all available OpenGL shaders and their paths.

Shaders are to be used in the 'glshader' config setting.

--fullscreen             Start in fullscreen mode.

--lang <lang_file>       Start with the language specified in <lang_file>.

--machine <type>         Emulate a specific type of machine. The machine type has

influence on both the emulated video and sound cards.
                        Valid choices are: hercules, cga, cga_mono, tandy,
                        pcjr, ega, svga_s3 (default), svga_et3000, svga_et4000,
                        svga_paradise, vesa_nolfb, vesa_oldvbe.

-c <command>             Run the specified DOS command before handling the PATH.

Multiple commands can be specified.

--noautoexec             Don't run DOS commands from any [autoexec] sections.

--exit                   Exit after running '-c <command>'s and [autoexec] sections.

--startmapper            Run the mapper GUI.

--erasemapper            Delete the default mapper file.

--securemode             Enable secure mode by disabling the MOUNT and IMGMOUNT


--socket <num>           Run nullmodem on the specified socket number.

--help                   Print help message and exit.

--version                Print version information and exit.

Internal Commands

dosbox has a comprehensive internal help system which can be accessed by running HELP command.

dosbox supports most of the DOS commands found in COMMAND.COM. In addition, the following extra commands are frequently used:


Program to mount local directories as drives inside dosbox.


A utility to mount disk images and CD‐ROM images in dosbox.


Change dosbox internal configuration on the fly. May not work with all options.


Program to reduce the amount of  memory available. Useful for old programs which  don't expect much memory to be free.


Make dosbox reread the directory structure. Useful if you changed something  on a mounted drive outside dosbox. Ctrl+F4 does this as well.


BOOT will start floppy images or hard disk images independent of the operating system emulation offered by dosbox. This will allow you to play booter floppies or boot to other operating  systems inside dosbox.


Configuration and language files use a format similar to Windows .ini files.  If no configfile is specified at the commandline, a file named dosbox-staging.conf (if present in the current directory) will be loaded automatically. We also will read and load dosbox.conf locally too, if dosbox-staging.conf isn't present.

If a configfile is specified at the commandline that one will be used instead. If no configfile is specified or found in the current directory then dosbox will load one from $XDG_CONFIG_HOME/dosbox/ (which defaults to ~/.config/dosbox/). It will try to create a new default config file if it does not exist yet.

Special Keys


Switch between fullscreen and window mode.


Pause/Unpause emulator.


Start the keymapper.


Swap mounted disk-image (only used with imgmount). Update directory cache for all drives.


Save a screenshot of the DOS pre-rendered image.


Save a screenshot of the rendered image.


Start/Stop recording sound output to a wave file.


Start/Stop recording video output to a zmbv file.


Mute/Unmute the audio.


Kill dosbox.


Capture/Release the mouse.


Slow down emulation (Decrease number of cycles/s).


Speed up emulation (Increase number of cycles/s).


Unlock speed (turbo button).

These are the default keybindings. They can be changed in the keymapper. More bindable actions can be found in the keymapper.


Saved/recorded files can be found in current_directory/capture (can be changed in the configfile). The directory has to exist prior to starting dosbox else nothing gets saved/recorded!

Once you increase your dosbox cycles beyond your computer's maximum capacity, it will produce the same effect as slowing down the emulation. This maximum will vary from computer to computer, there is no standard.


Any configuration option can be override using an environment variable. Environment variables starting with prefix DOSBOX are processed and interpreted as follows: DOSBOX_SECTIONNAME_PROPERTYNAME=value

For example, you can override Sound Blaster type to Sound Blaster Pro 2 this way:



To report a bug, please visit

See Also

You'll find long and detailed manual in README file in /usr/share/doc/dosbox-staging


DOSBox Staging project is maintained by the DOSBox Staging Team (

This manual page was written by Peter Veenstra <> and James Oakley <>, for the Debian system (but may be used by others), updated by Patryk Obara <> and Antti Peltola <> for DOSBox Staging project.


Dec 4, 2023