Fixing Common DOSBox-X Audio, Video, and Input Issues

DOSBox-X provides a wide range of configuration options that make it highly flexible, but that same depth can make diagnosing problems tricky. This page walks through the most common issues users encounter — from audio that refuses to play to games that crash on startup — and explains exactly what settings to change and why. Each accordion below covers one problem category with step-by-step remedies drawn directly from the DOSBox-X configuration reference.

Program runs too fast or too slow

Emulation speed in DOSBox-X is controlled by the cycles setting in the [cpu] section of your configuration file. This value represents the number of CPU instructions emulated per millisecond and has a large impact on how a program behaves.Quick keyboard adjustments (no restart required)DOSBox-X uses F12 as the default host key. Hold it and press the key below:

Shortcut	Effect
`F12` + `=`	Increase cycle count (speed up)
`F12` + `-`	Decrease cycle count (slow down)

Configuration-file remedies

[cpu]
# Let DOSBox-X choose automatically — best starting point
cycles = auto

# Older real-mode DOS games (286/8086 era)
cycles = 3000

# Windows 9x or demanding protected-mode games
cycles = max

If a game runs fine but music sounds sped-up or slowed-down, try cycles = fixed 20000 and adjust the number incrementally until music and gameplay feel correct.

The cycleup and cycledown keys let you fine-tune the value live while the program is running, which is often the fastest way to find the right number.

No sound or audio issues

Sound problems usually trace back to either DOSBox-X’s mixer being silenced, the wrong Sound Blaster type being emulated, or a mismatch between DOSBox-X’s defaults and what the program was configured to use.Step 1 — Confirm the mixer is on

[mixer]
nosound = false

When nosound = true, DOSBox-X runs in silent mode: the hardware is still emulated, but no audio is sent to your speakers.Step 2 — Check the Sound Blaster type

[sblaster]
# Default and most compatible for DOS games
sbtype = sb16

# Try these if sb16 doesn't work:
# sbtype = sb1
# sbtype = sb2
# sbtype = sbpro1
# sbtype = sbpro2
# sbtype = none   ← disables Sound Blaster entirely

Step 3 — Match the program’s sound-card setupMost DOS programs that ask for sound-card settings expect:

Setting	Default DOSBox-X value
Base I/O address	`220`
IRQ	`7`
DMA (8-bit)	`1`

If you ran the game’s setup program and chose different values, update the [sblaster] section in your DOSBox-X config to match.MIDI / MT-32 issues

[midi]
mididevice = default

Check that mididevice points to a valid output. On Linux, list available MIDI ports with aconnect -o; on Windows, the default Windows MIDI mapper is used unless you specify a different device name.

For MT-32 emulation, DOSBox-X supports the Munt library. Set mididevice = mt32 and ensure the MT-32 ROM files are placed in a location DOSBox-X can find them.

Mouse not working or not locking to the window

DOSBox-X captures the host mouse pointer and routes it to the guest DOS environment. If the mouse seems unresponsive, the issue is usually that the window has not captured the pointer yet.Capture the mouse

Click anywhere inside the DOSBox-X window to lock the pointer.
Press Ctrl+F10 to toggle the mouse lock on or off at any time.

Automatic locking on click

[sdl]
autolock = true

With autolock = false (the default), you must explicitly press Ctrl+F10 or use the menu to capture the mouse.INT 33h mouse driverDOS programs use the INT 33h software interface to communicate with the mouse. Confirm it is enabled:

[dos]
int33 = true

Setting int33 = false disables the built-in mouse driver entirely, which will make most DOS games unable to detect the mouse.

If the cursor moves erratically, try adjusting int33 max x and int33 max y in the [dos] section, or consult the game’s documentation for the expected screen resolution.

Game crashes at startup

A startup crash almost always means DOSBox-X is emulating hardware that the program is not expecting. Work through the following changes one at a time, testing after each.1. Change the machine type

[dosbox]
# Default — S3 Trio64 SVGA card
machine = svga_s3

# Plain VGA, no SVGA extensions
machine = vgaonly

# For very old games
machine = ega
machine = cga

2. Reduce memorySome DOS programs fail if they detect more RAM than they were designed for:

[dosbox]
memsize = 16

3. Change the CPU type

[cpu]
# Older protected-mode games
cputype = 386

# Games targeting mid-era hardware
cputype = 486

# Let DOSBox-X decide
cputype = auto

4. Switch to the normal coreThe dynamic recompiler core is faster but occasionally causes compatibility problems:

[cpu]
core = normal

5. Disable extended memory managersSome programs conflict with XMS or EMS support:

[dos]
xms = false
ems = false

Disabling XMS and EMS will break programs that depend on extended or expanded memory. Only use this as a diagnostic step, then re-enable the one that is not causing the conflict.

Wrong colors or corrupted display

Display problems can arise from a mismatch between the emulated video hardware and what the program expects, or from the host rendering pipeline.Change the output renderer

[sdl]
# Software renderer — most compatible
output = surface

# OpenGL (no bilinear filtering)
output = openglnb

# OpenGL (with bilinear filtering)
output = opengl

Try surface first; if that does not help, try opengl.Match the emulated video card

[dosbox]
machine = svga_s3        # S3 Trio64 — good for most SVGA games
machine = svga_et4000    # Tseng ET4000
machine = vgaonly        # Plain VGA, no SVGA extensions
machine = cga            # 4-color CGA
machine = cga_composite  # CGA with composite colour (e.g. old Sierra games)
machine = ega            # 16-color EGA

Enable aspect ratio correctionWithout aspect correction, 320×200 games appear stretched:

[render]
aspect = true

CGA games that rely on composite-color artifacts (producing brown, cyan, and other blended shades) require machine = cga_composite to display correctly. With plain cga, those games show raw 4-color output instead.

CD-ROM not detected

DOSBox-X uses the IMGMOUNT command to mount CD-ROM images and provides MSCDEX automatically for image mounts.Mounting an ISO image

IMGMOUNT D game.iso -t cdrom

Mounting a CD-ROM with audio tracksAlways use the .cue sheet file rather than the raw .iso when audio tracks are present — DOSBox-X reads the .bin/.wav/.mp3/.ogg tracks listed in the cue file:

IMGMOUNT D game.cue -t cdrom

MSCDEX already loadedIf your [autoexec] section or a startup batch file loads MSCDEX.EXE manually, remove that line — DOSBox-X installs its own MSCDEX automatically when you mount a CD-ROM image.

DOSBox-X supports cue sheets that reference FLAC, MP3, WAV, OGG Vorbis, and Opus audio files for CD-DA tracks. Using lossless FLAC or WAV gives the highest audio fidelity.

Cannot mount drives (secure mode)

If MOUNT and IMGMOUNT commands are unavailable or return an error about permissions, DOSBox-X is likely running in secure mode.

dosbox-x -securemode

The -securemode command-line flag disables commands that can access the host filesystem, including MOUNT, IMGMOUNT, and several others. This mode is intended for sandboxed or kiosk deployments.Resolution: Remove -securemode from the launch command or shortcut. If you did not add it yourself, check any wrapper scripts or launcher configurations.

Do not run DOSBox-X with -securemode removed if it was intentionally set for security reasons (for example, in a shared or public environment).

macOS: App Is Damaged and Cannot Be Opened

macOS Gatekeeper quarantines unsigned application bundles downloaded from the internet. This is a host OS restriction, not a DOSBox-X bug.Fix with one Terminal commandOpen Terminal, cd to the folder containing the unzipped DOSBox-X application, and run:

xattr -cr .

This removes the quarantine extended attribute from the app and all files inside it. After running the command, double-click DOSBox-X as normal.Alternative — System Settings

Attempt to open DOSBox-X (it will be blocked).
Open System Settings → Privacy & Security.
Scroll down to the security section and click Open Anyway next to the DOSBox-X entry.

The xattr -cr . approach is generally more reliable than the Privacy & Security panel, especially on macOS Ventura and later.

Windows: SmartScreen warning

Windows Defender SmartScreen may block unsigned or infrequently-downloaded executables, including new DOSBox-X releases.Steps to run anyway

Click 'More info'

When the blue SmartScreen dialog appears, click the More info link near the bottom of the dialog.

Click 'Run anyway'

A Run anyway button will appear. Click it to proceed with the installation or execution.

This warning appears because DOSBox-X releases are not commercially code-signed. The executable is safe — you can verify the SHA-256 hash of the downloaded file against the checksums published on the DOSBox-X releases page.

Joystick or gamepad not recognized

Joystick support in DOSBox-X depends on the SDL version used in the build and the emulated joystick type.Check the emulated joystick type

[joystick]
# auto — emulate based on what is connected (default)
joysticktype = auto

# Other options: 2axis, 4axis, 4axis_2, fcs, ch, none
joysticktype = 2axis

SDL1 vs SDL2 buildsSDL1 builds have more limited gamepad support and may only recognize XInput-compatible controllers. If your controller is not detected:

Use an SDL2 build (recommended — available on the DOSBox-X downloads page).
Or use an XInput wrapper such as Xoutput or x360ce on Windows to present your controller as an XInput device.

If you have multiple controllers connected, DOSBox-X will use the first one it detects. Disconnect unused controllers if the wrong one is being used.

Keyboard layout is wrong

If keys produce unexpected characters (for example, Y and Z are swapped on a German keyboard), the keyboard layout inside DOSBox-X does not match your physical keyboard.Change layout at runtime using KEYB

KEYB DE        # German
KEYB FR        # French
KEYB UK        # United Kingdom
KEYB ES        # Spanish

Set layout permanently in the config file

[dos]
keyboardlayout = de

Use none to disable any layout remapping and pass raw scan codes directly.Non-US keyboards with SDL1 buildsIf your keyboard still misbehaves with SDL1 builds, enable scan-code mode:

[sdl]
usescancodes = true

The usescancodes option bypasses SDL’s key-symbol translation and reads hardware scan codes directly. This resolves most layout problems on non-US keyboards but may not work on all operating systems.

Saving states fails or behaves unexpectedly

DOSBox-X supports up to 100 save slots for its save-state feature.Check the active save slot

[dosbox]
# Select which slot to use (1–100)
saveslot = 1

You can also change the active slot at runtime from File → Save/Load State in the menu.Common failure reasons

Disk full: Save states can be large (several megabytes). Ensure the drive where DOSBox-X stores state files has free space.
Version mismatch: A state saved with one version of DOSBox-X may not load cleanly in a different version.

Force-loading a mismatched state

[dosbox]
forceloadstate = true

When forceloadstate = true, DOSBox-X will attempt to load a save state even if it detects a mismatch in the DOSBox-X version, machine type, program name, or memory size. Use this carefully — a mismatched state can cause instability.

Getting Started

Configuration

Drives & Storage

Emulation Features

Troubleshooting

Fixing Common DOSBox-X Audio, Video, and Input Issues

Build docs developers (and LLMs) love

Getting Started

Configuration

Drives & Storage

Emulation Features

Troubleshooting

Documentation Index

Build docs developers (and LLMs) love