- SoundBlaster 16 / SoundBlaster Pro I & II / SoundBlaster I & II
      By default DOSBox provides SoundBlaster 16 level 16-bit stereo sound.
      You can select a different SoundBlaster version in the configuration of
      DOSBox. AWE32 music is not emulated as you can use MPU-401 instead.

Basically you can often get equivalent or better results by selecting SB16 for digital effects, and General MIDI for music, in the games sound setup. For General MIDI you typically will want to set mididevice = fluidsynth in your DOSBox config file and specify a suitable sound-font. See the MIDI page for more information.

Further reading and comments available in this vogons forum discussion.

`oplrate`, `gusrate`, and `tandyrate` are gone?

Their rates are controlled by the mixer rate, leaving only the pcrate, which can be adjusted to avoid harmonics, in rare cases.

MIDI

How can I tell what CM32 rom file version I have?

A console message will describe the version of ROM being used, for example:

MT32: Initialized CM-32L/LAPC-I Control v1.02

Or possibly easier, run the mixer /listmidi command from DOSBox Staging.

[Top]

Configuration

Where is the config file?

The location of the default dosbox-staging.conf config file depends on the host OS and method of packaging.

Linux: ~/.config/dosbox/
Linux Flatpak: ~/.var/app/io.github.dosbox-staging/config/dosbox/
macOS: ~/Library/Preferences/DOSBox/
Windows: C:\Users\<username>\AppData\Local\DOSBox\

Linux users can customize the parent (.config/) location by setting the XDG_CONFIG_HOME environment variable.

If you still cannot find dosbox-staging.conf on your system, open the relevant command prompt for your system, change to the Dosbox-Staging directory, then run one of the commands below accordingly:

Linux - Bash: ./dosbox --printconf
MacOS - Terminal: ./dosbox --printconf
Windows - CMD: dosbox.exe --printconf
Windows - Powershell: .\dosbox.exe --printconf

Instead of starting Dosbox-Staging, the --printconf switch will only display where dosbox-staging.conf is located on your system.

The third way to find the location of dosbox-staging.conf on your system is to open Dosbox-Staging, then click on the DOSbox Status Window. At the top of the DOSbox Status Window, look for the line CONFIG: Loaded primary config file ''. The location of dosbox-staging.conf will be displayed between the two single-quotation marks on that line.

A fourth way to find the location of dosbox-staging.conf on your system is to open Dosbox-Staging, type config -l, and press Enter. The location will be listed under the Primary Config File: heading.

After finding the location of dosbox-staging.conf, make a shortcut to this file so that you will be able to change Dosbox-Staging's settings as needed.

How do I run Dosbox-Staging in portable mode?

Download and extract Dosbox-Staging to a folder of your choice.
Open the relevant command prompt for your system, change to your newly created Dosbox-Staging directory, and create an empty file called dosbox-staging.conf:

Linux - Bash: touch dosbox-staging.conf
MacOS - Terminal: touch dosbox-staging.conf
Windows - CMD: type nul > dosbox-staging.conf
Windows - Powershell: New-Item dosbox-staging.conf

Double-click on Dosbox-Staging's executable to start Dosbox-Staging.
Open dosbox-staging.conf in a text editor. You will see that dosbox-staging.conf has now been populated with Dosbox-Staging's default program values.

What is the default CPU cycle count for real and protected mode programs in Dosbox-Staging?

Dosbox-Staging 0.81.2 and earlier use a default of 3000 cycles for real mode programs, and 100% (as fast as your host CPU can handle it) for protected mode programs. Examples of real mode games include but are not limited to Crystal Caves, Epic Pinball, Jetpack, Lemmings, and Wolfenstein 3D.

Dosbox-Staging 0.82 RC and later also use a default of 3000 cycles for real mode programs, but a default of 60000 cycles for protected mode programs. Examples of protected mode games include but are not limited to Blood, Doom II, Duke Nukem 3D, Jazz Jackrabbit, and Quake.

How Do I Adjust the CPU Cycle Count in the DOSBox Staging Config File?

You can adjust the number of CPU Cycles that DOSBox Staging emulates per second in any of the following ways:

Open your dosbox-staging.conf, scroll down to [cpu], and change the number next to cpu_cycles or cpu_cycles_protected to the number of CPU cycles you want to use.
Open your dosbox-staging.conf, scroll down to [autoexec], and type cpu_cycles xxxxx or cpu_cycles_protected xxxxx, replacing xxxxx with the number of CPU cycles you want to use.
At the DOSBox Staging command prompt, simply type cpu_cycles xxxxx or cpu_cycles_protected xxxxx and press Enter, replacing xxxxx with the number of CPU cycles you want to use. Note that if you do this from the DOSBox Staging command prompt, and then you close DOSBox Staging, you will have to adjust the cycles again when you open DOSBox Staging again at a later time.
Adding the line cpu_cycles xxxxx or cpu_cycles_protected xxxxx in your game's .bat file, replacing xxxxx with the number of CPU cycles you want to use.

Adjusting the CPU cycle count will be necessary for CPU Speed Sensitive Games that run too fast if the CPU Cycle count is set too high, such as Duke Nukem 2.

Other games, such as Perfect Assassin, crash if the CPU Cycle count is set to max.

Emulated CPU	MHz	Approximate CPU Cycles	Suggested Host CPU
8088	4.77	240
286	8	750
286	12	1510
286	25	3300
386DX	25	4595
386DX	33	6075
486DX	33	12019
486DX2	66	23880
486DX4	100	33445
486DX5	133	47810
Intel Pentium	60	31545
Intel Pentium	66	35620
Intel Pentium	75	43500
Intel Pentium	90	52000
Intel Pentium	100	60000
Intel Pentium	120	74000
Intel Pentium	133	80000	Intel Core 2 Duo 3.3 GHz
Intel Pentium MMX	166	97240
Intel Pentium II	300	200000
Intel Pentium III	866	407000
AMD K6	166	110000
AMD K6	200	130000
AMD K6-2	300	193000
AMD Athlon	600	306000

(Chart is originally from https://dosbox-x.com/wiki/Guide%3ACPU-settings-in-DOSBox%E2%80%90X#_cycles.)

Advanced CPU Cycle Count Configuration:

Within your dosbox-staging.conf in the [cpu] section, the cycles=auto and cycles=max settings can be parameterized to have different startup defaults.

The syntax is:

cycles=auto ["realmode default"] ["protected mode default"%] [limit "cycle limit"]

cycles=max ["protected mode default"%] [limit "cycle limit"]

Example:

cycles=auto 5000 80% limit 20000 will use cycles=5000 for real mode games, 80% CPU throttling for protected mode games along with a hard cycle limit of 20000.

Note

If you run the above command from a .BAT file, you must type it as cycles=auto 5000 80%% limit 20000 because %% is for variables.

How Much EMS And XMS RAM for DOS Games Does Dosbox-Staging Support?

In Dosbox-Staging 0.81 or later, the maximum supported memsize in dosbox-staging.conf is 3072, or 3072 MB.

In Dosbox-Staging 0.80.1 or earlier, the maximum supported memsize in dosbox-staging.conf is 63, or 64 MB.

How do I access Dosbox-Staging's internal help screens?

Open Dosbox-Staging.
Type commandhere /? and press Enter.

Important: Replace commandhere with the command of the help screen you want to access, such as mount, imgmount, dir, or loadfix.
Commonly Used Examples: mount /?, imgmount /?, dir /?, or loadfix /?

Can I override just some settings for a game?

Yes. You can use the -conf or -userconf parameters to load multiple "layered" configurations, where subsequent config files override settings from the prior ones (except the autoexec section, which is merged and launched in sequence). For example:

$ ./dosbox -userconf -conf A.conf -conf B.conf

First, your global configuration file is loaded (-userconf).
Second, A.conf is loaded, overriding any settings from your global configuration.
Finally, B.conf is loaded, further overriding settings applied by A and the global configuration.

Default behavior:

If no -conf parameters are passed, then dosbox-staging.conf from current working directory is used (only this file; it doesn't matter directory is loaded as drive C or not).
If there's no dosbox-staging.conf in current working directory, then global file is used (default path for stable release: ~/.config/dosbox/dosbox-staging.conf).
If global file does not exist, then a new one is generated.

How do I use a custom `.conf` file specifically configured for one game?

To use a custom .conf file specifically configured for one game, you will need to use --noprimaryconf and --conf together when starting Dosbox-Staging either from the commandline or a desktop shortcut:

$ ./dosbox --noprimaryconf --conf path\to\filenamehere.conf

--noprimaryconf skips the global configuration file upon Dosbox-Staging startup.
--conf path\to\filenamehere.conf runs the specific .conf file you want to use for the game in question. Replace path\to\filenamehere.conf with the specific location of the .conf file you intend to use.

A common example of --noprimaryconf and --conf being used together is creating Windows, MacOS, or Linux desktop shortcut(s) that run a DOS game upon Dosbox-Staging startup, utilizing specific Dosbox-Staging settings for the DOS game in question.

You can see exactly which files were loaded on stderr/terminal output (I know, not the best place); they are prefixed with CONFIG, e.g.:

$ ./dosbox 
dosbox-staging version 0.x
---
CONFIG: Loading primary file /home/dreamer_/.config/dosbox/dosbox-staging.conf

How is `[autoexec]` handled when using multiple config files?

File a.conf has "@echo A" inside, file b.conf has "@echo B" inside - when user runs:

$ ./dosbox -c "@echo C" -conf a.conf -conf b.conf

Then DOSBox Staging shell will output:

A
B
C

[Reference #1] | [Reference #2]

Update the global config file

After you upgrade your DOSBox Staging binary it's wise to update your dosbox-staging.conf as well. Your existing settings will be retained however extraneous comments will be dropped.

You have to run DOSBox Staging first then type in the following command:

C:\>config -wc

Windows

Open dosbox-staging.conf in a text editor.
Go to the [autoexec] section.
Add the line mount c //PC-NAME/foldernamehere/dosgames/.

Important: You cannot mount the first directory, in this case foldernamehere. You have to use a subdirectory of foldernamehere, in this case dosgames. Additionally, the trailing slash / after dosgames is mandatory or the mount will not complete successfully.
Replace //PC-NAME/foldernamehere/dosgames/ with the specific network share path you want to use on your system.

Add c: to the next line.
Save and close dosbox-staging.conf.
Open Dosbox-Staging and you will be in your mounted C drive.

Linux - SAMBA network shares

Important: Verify that cifs-utils or a similarly named equivalent package for your Linux distro is installed before following the steps below:

Create your mount point: sudo mkdir /mnt/samba_share
Mount the SAMBA share: sudo mount -t cifs //server_ip/share_name /mnt/samba_share

If you instead want a persistent mount that survives reboots, open /etc/fstab in a text editor, add the following line, and save the file:
//server_ip/share_name /mnt/samba_share cifs defaults 0 0
You will then need to open Bash and run sudo mount -a to mount the share immediately.

Open dosbox-staging.conf in a text editor.
Go to the [autoexec] section.
Add the line mount c /mnt/samba_share.
Add c: to the next line.
Save and close dosbox-staging.conf.
Open Dosbox-Staging and you will be in your mounted C drive.

Alternatively, if you also want to use passwords for your Linux-mounted SAMBA shares, read this page accordingly.

How Do I Adjust Mouse Sensitivity?

Modify the mouse_sensitivity = 100 setting in the [mouse] section of dosbox-staging.conf as you see fit.

Increasing the number increases the mouse sensitivity, while decreasing the number does the opposite.

How Do I Enable Raw Mouse Input?

Set mouse_raw_input = true in the [mouse] section of dosbox-staging.conf.

Special Keys

When running DOSBox-Staging, press any of the following key combinations below for their respective functions:

Key	Description
Alt + Enter	Switch between fullscreen and window mode.
Alt + Pause	Pause / Unpause emulator.
Ctrl + F1	Start the keymapper.
Ctrl + F4	Swap mounted disk image, scan for changes on all drives.
Alt + F5	Save a screenshot of the rendered image.
Ctrl + F5	Save a screenshot of the DOS pre-rendered image.
Ctrl + F6	Start / Stop recording sound output to a wave file.
Ctrl + F7	Start / Stop recording video output to a zmbv file.
Ctrl + F8	Mute / Unmute the audio.
Ctrl + F9	Shutdown emulator.
Ctrl + F10	Capture / Release the mouse.
Ctrl + F11	Slow down emulation.
Ctrl + F12	Speed up emulation.
Alt + F12	Unlock speed (turbo button / fast forward).

Additional keyboard shortcuts may be available, depending on the machine type being emulated. See the Video Cards section for more details.

[Top]

Video

Pipeline Breakdown

DOS video mode > SW Scaler > HW Processing output= > Host output texture_renderer=

DOS video mode: this is an emulated video mode used by the game. For example, the game might be drawing a 320x200 pixel image of VGA data to the emulated video card, thinking it's running on CRT at 70 Hz. But really its just writing to a 320x200 memory block in DOSBox.
SW Scaler: historically, the next step scaled up the image using software routines. Using things like normal2x are no longer needed because the next step can do that in hardware.
HW Processing: will use accelerated routines to scale the image to the desired window size. The output = setting also lets us fine-tune the type of scaling - be it "soft", nearest-neighbour (nb), or pixel-perfect (pp). If we're processing the image using OpenGL routines (output = opengl*) then the configured glshader = will also be applied. If we're processing using SDL's accelerated routines (output = texture*), then we forfeit the ability to apply GL shaders, however we still get accelerated scaling brokered by SDL.
Host output: Finally we have the interface to the host, and deciding what hardware API should be used to hand over the processed image. This is best left to auto to let SDL pick the best choice (be it OpenGLES2 on the Raspberry Pi, Vulkan on macOS, OpenGL on Linux, or Direct3D on Windows).

What's considered the best generic choice

If you don't care about glshaders and prefer sharp pixels, then output = texturenb and texture_renderer = auto is universally compatible across platforms (macOS, RPi, Window, GNU/Linux, and even others). This works great on everything we've thrown at it.

... But if you want shaders, then use output = openglnb and texture_renderer = auto.

Additionally, you can switch from nb to pp, if you want pixel perfect (in both scenarios).

Does that mean `output = texturenb` with `texture_renderer = opengl` is the same as just having `output = openglnb`?

Yes, in that both images will be scaled to nearest neighbour.
No, in that output = opengl means the DOS output will be processed using OpenGL routines, and the selected glshader will be applied. Whereas output = texture means the DOS output will be processed using SDL's routines, so glshaders won't be applied.

[Reference]

Is a scaler needed or ignored if using `windowresolution = large`?

For standard scaling, set scaler = none and let it be done in hardware instead (the only remaining use for scaler is for people who still want to use things like 2xsai, super2xsai, supereagle, etc..). [Reference]

[Top]

Miscellaneous

Keyboard shortcut not working in DOS application

If a keyboard combination does not work in a DOS application, it is likely being caught either by DOSBox Staging or even earlier by the host operating system or window manager.

First check if the keyboard shortcut is being caught by DOSBox Staging by checking the keyboard mapper. If this is the case, you can use the keyboard mapper to change or delete the mapping to resolve the conflict.

If it is not DOSBox Staging that is catching the keyboard shortcut, it is probably the host OS or window manager. An example of a key that will typically be caught by the host OS is the Print Screen key, or the CTRL-ALT-DEL combination. For some host operating systems, such as Linux, you can typically change the keyboard shortcuts to prevent such clashes.

If you cannot prevent the clash, you may be able to use the DOSBox Staging keyboard mapper to remap the key combination to something else.

Note

If regular function keys (e.g., F1) don't work in DOS applications running under DOSBox Staging, check if your keyboard has an "Fn" key. On many modern keyboards the legacy function keys have been re-used for other functions such as multimedia keys (Mute, Volume, etc), and will not function as regular function keys unless you also press the "Fn" modifier key, e.g., Fn-F1. On some systems, such as ThinkPads, the function keys can be restored to their original function using a BIOS setting to invert the function key functionality, such that F1 is again F1 and the multimedia functions will instead need the Fn key.

How to run your command-line interpreter of choice exclusively?

This usually refers to running in permanent mode. The command-line interpreter process fully takes over instead of being nested under DOSBox Staging's own COMMAND.COM.

To start DOSBox Staging with FreeDOS FreeCOM running in permanent mode add these lines to your global config file dosbox-staging.conf under the [autoexec] section (assuming FreeCOM is installed to C:\):

[autoexec]
C:
COMMAND.COM /P

Loading device drivers

Here's late DR-DOS DEVICE.COM that works with DOSBox Staging. We can't include it since its not open source:

Download link

Disc swapping

Just press CTRL and F4 at the same time while in DOS mode and when asked by the program to cycle through your mounted CD/disc images while relying on IMGMOUNT. All CD images must have been properly declared in your [autoexec] section. Example given of such section with the game RAMA:

[autoexec]
imgmount d /home/pc/isos/rama/rama-1.iso /home/pc/isos/rama/rama-2.iso /home/pc/isos/rama/rama-3.iso -t cdrom
C:
CD RAMA
CALL RAMADOS.BAT
EXIT

Please note that some games like Under a Killing Moon do support multiple CD-Rom drives hence no need to swap disc each time, it will be transparent for users.

DOS Games That Use CD Digital Audio (CDDA) Tracks

For a comprehensive list of DOS games that use CD Digital Audio tracks, please refer to https://www.vogons.org/viewtopic.php?p=673031#p673031.

If you plan on using CD images (CUE / BIN, CUE / GOG, DAT / GOG file pairs, etc) in Dosbox-Staging, please use only the imgmount command accordingly.

Do Not Use Daemon Tools to Mount CD / Disc Images in Dosbox Staging

Do not mount CD / disc images in DOSBox Staging using Daemon Tools or other similar programs.

Instead, use Dosbox Staging's imgmount command only.

If you do use Daemon Tools or other similar programs with Dosbox Staging, you will run into game compatibility issues like this. In order to reduce the future likelihood of running into said compatibility issues, use imgmount only.

Does the `ver` setting just do the same thing as typing `VER` inside DOS?

The ver setting generally functions the same as VER SET. The VER command itself shows the DOS version, whereas VER SET will set a DOS version. With the ver setting you can specify a DOS version at start. [Reference]

Files/directories not listed/refreshed

While working in DOS mode (the famous C:\> prompt) it's possible to add/remove files or directories from the host Operating System at the same time. For instance you're installing a game which takes few minutes to complete. In parallel you decide to copy over a patch (eg. patch.exe) into the game directory from your Operating System. At the end of the installation if you go the game directory and type in the DIR command patch.exe will not be listed there. For it to be listed you'll have to refresh the DOS drive's cache. You have several ways to accomplish such task.

`rescan`

The rescan command will force DOSBox to re-read the directory structure. At the DOS prompt simply enter this command:

C:\>rescan

`CTRL+F4`

Same as for the rescan command above. Just press CTRL and F4 at the same time while in DOS mode to have your drive's cache refreshed. It's the same key-combination to cycle through your mounted CD/disk images when using IMGMOUNT. Some games like Under a Killing Moon do support multiple CD-Rom drives hence no need to swap disc each time, it will be automatic.

mount folder as floppy

Thanks again to @ripsaw8080 for this tip. The workaround is being described there. In short the cache is not used for floppy drives. Please do note there are potential drawbacks with this method.

`PATH` command

PATH tells DOS which directory(ies) should be searched for external commands after DOS searches your current working directory. DOS searches the paths in the order specified in the PATH command. Therefore the leftmost location will take precedence over the other locations. If you enter the PATH command without options, the program will display the currently set path. You can tell DOS to search more than one path by specifying several pathnames separated by semicolons.

Let's assume you added a U: drive to your environment:

[autoexec]
mount u ~/.config/dosbox/utils
set PATH=u:\;%PATH%

Binaries located in the U: drive will take precedence over any other locations.

Translations

DOSBox Staging bundles the following translations: Dutch, French, German, Italian, Polish, Russian and Spanish. Thanks to the @translations team! Any help always welcome to improve the current ones or to add more.

DOSBox Staging defaults to using the same language as the host OS (if available), or to English otherwise. This can be overruled by manually setting the appropriately LANG environment variable, or by starting DOSBox Staging with the -lang option. e.g., dosbox -lang fr for French.

Alternatively the language can be specified by simply editing your global config file (dosbox-staging.conf):

[dosbox]
# de, en, es, fr, it, nl, pl, and ru
language = de

Translations files are located under the resources directory.

Where to find patch for a game?

The Patches Scrolls usually is a good place to start with.

Where to download Windows 32-bit binaries?

We include our Windows 32-bit binary download links on our GitHub releases page.

Enabling UTF-8 Support for Windows CMD

Follow the instructions as shown at https://github.com/dosbox-staging/dosbox-staging/pull/3052#issuecomment-1782134730.

[Top]

Hard disk image requirements

Each partition in the hard disk image must use the FAT16 filesystem, while the size of each partition must be 2 GB or less.

[Top]

How do I view the Dosbox-Staging status window after Dosbox-Staging crashes?

Open your operating system's command line interface:

In the command prompt window that opens, navigate to your Dosbox-Staging folder and run Dosbox-Staging.
If Dosbox-Staging crashes, the Dosbox-Staging status window will not disappear.

[Top]

Can I run Dosbox-Staging in a hypervisor, VM, smartphone, or emulator?

The Dosbox-Staging team strongly discourages this because of real-time audio processing issues, such as sound stuttering.

Instead, please run Dosbox-Staging natively on a PC. Although you might be able to run Dosbox-Staging on a phone, Dosbox-Staging does not officially support that. As a result, do not expect any help from the dev team and do not raise any phone-related issue tickets either.

[Top]

General

How-to's

Lists

Audio

Video

Issues

Dev

Misc

Wiki Home · Website · Discord · Open Collective · Mastodon
Latest stable binary releases for Windows, macOS, or Linux
Unstable development snapshots also available for testing

Audio

Are AWE32/64 soundcards emulated?

oplrate, gusrate, and tandyrate are gone?

MIDI

How can I tell what CM32 rom file version I have?

Configuration

Where is the config file?

How do I run Dosbox-Staging in portable mode?

What is the default CPU cycle count for real and protected mode programs in Dosbox-Staging?

How Do I Adjust the CPU Cycle Count in the DOSBox Staging Config File?

Advanced CPU Cycle Count Configuration:

How Much EMS And XMS RAM for DOS Games Does Dosbox-Staging Support?

How do I access Dosbox-Staging's internal help screens?

Can I override just some settings for a game?

How do I use a custom .conf file specifically configured for one game?

How is [autoexec] handled when using multiple config files?

Update the global config file

How do I mount a network share in Dosbox?

Windows

Linux - SAMBA network shares

How Do I Adjust Mouse Sensitivity?

How Do I Enable Raw Mouse Input?

Special Keys

Video

Pipeline Breakdown

What's considered the best generic choice

Does that mean output = texturenb with texture_renderer = opengl is the same as just having output = openglnb?

Is a scaler needed or ignored if using windowresolution = large?

Miscellaneous

Keyboard shortcut not working in DOS application

How to run your command-line interpreter of choice exclusively?

Loading device drivers

Disc swapping

DOS Games That Use CD Digital Audio (CDDA) Tracks

Do Not Use Daemon Tools to Mount CD / Disc Images in Dosbox Staging

Does the ver setting just do the same thing as typing VER inside DOS?

Files/directories not listed/refreshed

rescan

CTRL+F4

mount folder as floppy

PATH command

Translations

Where to find patch for a game?

Where to download Windows 32-bit binaries?

Enabling UTF-8 Support for Windows CMD

Hard disk image requirements

How do I view the Dosbox-Staging status window after Dosbox-Staging crashes?

Can I run Dosbox-Staging in a hypervisor, VM, smartphone, or emulator?

General

How-to's

Lists

Audio

Video

Issues

Dev

Misc

`oplrate`, `gusrate`, and `tandyrate` are gone?

How do I use a custom `.conf` file specifically configured for one game?

How is `[autoexec]` handled when using multiple config files?

Does that mean `output = texturenb` with `texture_renderer = opengl` is the same as just having `output = openglnb`?

Is a scaler needed or ignored if using `windowresolution = large`?

Does the `ver` setting just do the same thing as typing `VER` inside DOS?

`rescan`

`CTRL+F4`

`PATH` command