dosbox - Man Page

an x86/DOS emulator with sound/graphics


dosbox [-fullscreen] [-startmapper] [-noautoexec] [-securemode] [-userconf] [-scaler scaler|-forcescaler scaler] [-conf configfile] [-lang langfile] [-machine machinetype] [-socket socketnumber] [-c command] [-exit] [NAME]

dosbox --version

dosbox --printconf

dosbox --editconf [editor]

dosbox -eraseconf

dosbox -resetconf

dosbox --list-glshaders

dosbox -erasemapper

dosbox -resetmapper

dosbox -opencaptures program


This manual page briefly documents dosbox-staging, an x86/DOS emulator.

The optional NAME argument should be a DOS executable or a directory. If it is a dos executable (.com .exe .bat) the program will  run automatically. If it is a directory, a DOS session will run with  the directory mounted as C:\.

For an introduction type INTRO inside dosbox.


A summary of options is included below.


Start dosbox in fullscreen mode.


Start the internal keymapper on startup of dosbox. You can use it to change the keys dosbox uses.


Skips the [autoexec] section of the loaded configuration file.


Same as -noautoexec, but adds  -securemode at the end of AUTOEXEC.BAT (which in turn disables any changes to how the drives are mounted inside dosbox)


Load the configuration file located in ~/.config/dosbox. Can be combined with the -conf option.

-scaler scaler

Uses the graphical scaler specified by scaler. See the configuration file for the available scalers

-forcescaler scaler

Similar to the -scaler parameter, but tries to force usage of the specified scaler even if it might not fit.

-conf configfile

Start dosbox with the options specified in configfile. This file has a section in which you can put commands you wish to execute on startup. Multiple configfiles can be present at the commandline.

-lang langfile

Start dosbox with the language specified in langfile.

-machine machinetype

Setup DOSBox to emulate a specific type of machine. Valid choices are:


Hercules Graphics Card (monochrome)


IBM Color Graphics Adapter


IBM CGA attached to monochrome display (monochrome)




Tandy Graphics Adapter (Tandy 1000)


IBM Enhanced Graphics Adapter


IBM Video Graphics Array (see below)


VESA SVGA - VESA BIOS Extensions (VBE) 1.2


VESA SVGA - VBE 2.0 with Linear Frame Buffer disabled


VESA SVGA - Paradise Systems PVGA1A - VBE 2.0


VESA SVGA - Tseng ET3000 - VBE 2.0


VESA SVGA - Tseng ET4000 - VBE 2.0


VESA SVGA - S3 Trio - VBE 2.0

The default is svga_s3.

For some special VGA effects the machinetype vgaonly can be used, note that this disables SVGA capabilities and might be slower due to the higher emulation precision."

The machinetype affects the video card and the available sound cards.

-socket socketnumber

Passes the socket number socketnumber to the nullmodem emulation. See README for details.

-c command

Runs the specified command before running file. Multiple commands can be specified. Each command should start with -c though. A command can be: an Internal Program, a DOS command or an executable on a mounted drive.


dosbox will close itself when the DOS program specified by file ends.


Output version information and exit. Useful for frontends.

--editconf [editor]

Open the default configuration file in a text editor. If no editor name is given, then use the program from EDITOR environment variable, otherwise DOSBox will try to guess the name.

-opencaptures program

calls program with as  first parameter the location of the captures folder.


Prints the location of the default configuration file.

-eraseconf,  -resetconf

removes the default configuration file.


List available GLSL shaders and their directories. Results are useable in the "glshader = " conf setting.

-erasemapper,  -resetmapper

removes the mapperfile configured in the clean default configuration file.

Internal Commands

dosbox supports most of the DOS commands found in In addition, the following extra commands are available:

MOUNT [-t type] [-size size] driveletter sourcedirectory [-usecd number] [-label drivelabel] [-freesize freesize]

MOUNT -listcd (or -cd)

MOUNT -u driveletter

Program to mount local directories as drives inside dosbox.


The driveletter inside dosbox (eg. C).


The local directory you want to have inside dosbox.

-t type

Type of the mounted directory. Supported are: dir (standard), floppy, cdrom.

-size drivesize

Sets the size of the drive. See the examples in the README for details.

-freesize size_in_mb

Sets the amount of free space available on a drive in MB's. This is a more simple version of -size.

-label drivelabel

Sets the name of the drive to drivelabel. Needed on some systems if the cd label isn't read correctly. Useful when a  program can't find its cdrom. If you don't specify a label and no lowlevel support is selected (-usecd #):

For win32: label is extracted from "Real Drive".

For Linux: label is set to NO_LABEL.
If you do specify a label this label will be kept as long as the drive

is mounted. It will not be updated !!

-usecd number

Forces to use SDL cdrom support for drive number. Number can be found by -listcd/-cd.

-listcd (or -cd)

Displays all detected cdrom drives and their numbers. Use with -usecd.


Unmounts a mounted drive. Doesn't work on virtual Drives (like Z:\)


To mount your /home/dos/dosgames directory as C drive in dosbox:

mount c /home/dos/dosgames


Display the amount of free memory

CONFIG [-writeconf] [-writelang] file

CONFIG -securemode

Write the current configuration or language settings to file, which is located on the local filesystem. Not a mounted drive in dosbox.


Switches dosbox to a more secure mode. In this mode the internal commands MOUNT, IMGMOUNT and BOOT won't work. It's not possible either to create a new configfile or languagefile in this mode. (Warning you can only undo this mode by restarting dosbox.)

The configuration file controls various settings of dosbox: The amount of emulated memory, the emulated soundcards and many more things. It further allows access to AUTOEXEC.BAT.

The language file controls all visible output of the internal commands and the internal dos. See the section Files for more information.

LOADFIX [-size] [programname] [parameters]


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


The name of the program which is executed after loadfix eats up its memory.


Parameters given to the programname executable.


The amount of memory to eat up (in kb). Example -32, -64 or -128


Frees all memory eaten up by loadfix.

RESCAN [-All] [Drive:]

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


Reread directory structure for all drives.


Reread directory structure for drive Drive:

If both -All and Drive: are missing, then the current drive is used.


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

Read the README of dosbox for the full and correct syntax.


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.

Read the README of dosbox for the full and correct syntax.


You need to enable IPX networking in the configuration file of dosbox. All of the IPX networking is managed through the internal dosbox program IPXNET. For help on the IPX networking from inside dosbox, type IPXNET HELP and the program will list out the commands and relevant documentation.

Read the README of dosbox for the full and correct syntax.


Keyb can change the keyboardlayout and the codepage used inside dosbox.

Read the README of dosbox for the full and correct syntax.


Configuration and language files use a format similar to Windows .ini files.  If no configfile is specified at the commandline, a file named dosbox.conf (if present in the current directory) will be loaded automatically. 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.(png)


Start/Stop recording sound output to a wave file.


Start/Stop recording video output to a zmbv file.


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.

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 !

Note: 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.

System Requirements

Fast machine. My guess would be Pentium-2 400+ to get decent emulation of games written for an 286 machine. For protected mode games a 1 Ghz machine is recommended and don't expect them to run fast though!! Be sure to read the next section on how to speed it up somewhat.

To run resource-demanding games

dosbox emulates the CPU, the sound and graphic cards, and some other stuff, all at the same time. You can overclock dosbox by using Ctrl+F12, but you'll be limited by the power of your actual CPU. You can see how much free time your true CPU has by various utils (top).  Once 100% of your real CPU time is used there is no further way to speed up dosbox unless you reduce the load generated by the non-CPU parts of dosbox.


Close every program but dosbox.

Overclock  dosbox until 100% of your CPU is used. (Ctrl+F12)

Since VGA emulation is the most demanding part of dosbox in terms of actual CPU usage, we'll start here. Increase the number of frames skipped (in increments of one) by pressing Ctrl+F8. Your CPU usage should decrease. Go back one step and repeat this until the game runs fast enough for you. Please note that this is a trade off: you lose in fluidity of video what you gain in speed.


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 render aspect this way:



While we hope that, one day, dosbox will run virtually all programs ever made for the PC... we are not there yet. At present, dosbox run on a 1.7 Gigahertz PC is roughly the equivalent of a 25MHz 386 PC. While the 0.60 release has added support for "protected mode" allowing for more complex and recent programs,  but note that this support is early in development and nowhere near as complete as the support for 386 real-mode  games (or earlier). Also note that "protected mode" games need substantially more resources and may require a much faster processor for you to run it properly in dosbox.


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 <> for dosbox-staging project.


Jan 23, 2021