Skip to main content

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 presents you with a DOS command prompt the moment it launches, but to run your own programs you need to tell it where to find them by mounting a host folder as a virtual DOS drive. This quickstart walks you through launching DOSBox-X, setting up a working configuration file, mounting a directory, navigating the DOS shell, and running a program — all in a few straightforward steps.

​
Before You Begin

Make sure DOSBox-X is already installed on your system. If not, see the Installation page for platform-specific instructions.
1

Launch DOSBox-X

Start DOSBox-X using the method appropriate for your platform:
Double-click the DOSBox-X shortcut on your Desktop or Start Menu, or right-click a folder in Windows Explorer and choose Open with DOSBox-X if you enabled shell context menus during installation.
You will see the DOSBox-X window open with a Z:\> prompt and a drop-down menu bar at the top. The Z: drive is an internal virtual drive that holds DOSBox-X’s built-in utilities.
Type HELP at the Z:\> prompt to see a list of available built-in commands and their descriptions.
2

Create or Locate a Configuration File

DOSBox-X reads its configuration from a file called dosbox-x.conf. On startup, DOSBox-X searches for this file in the following order:
  1. The current working directory (the folder from which DOSBox-X was launched)
  2. The user configuration directory (platform-specific — for example %APPDATA%\DOSBox-X on Windows or ~/.config/dosbox-x on Linux)
If no config file is found, DOSBox-X uses built-in defaults. To create a minimal config that controls the machine type, memory, rendering, and auto-run commands, save the following as dosbox-x.conf in your preferred working directory:
[dosbox]
machine = svga_s3
memsize = 16

[render]
output = opengl
aspect = true

[autoexec]
mount c ~/dosgames
c:
The [autoexec] section contains DOS commands that DOSBox-X executes automatically at startup. Adjust the path in mount c to point to wherever you store your DOS software. On Windows, use a backslash path such as C:\Users\you\dosgames.
You can generate a fully commented configuration file from within DOSBox-X by running config -wc dosbox-x.conf at the DOS prompt. This writes every available option with its description to the file.
3

Mount a Host Folder as a DOS Drive

If you did not set up an [autoexec] section, you can mount a folder manually from the DOSBox-X shell. The MOUNT command maps a host directory to a DOS drive letter.
MOUNT C C:\Users\you\dosgames
Replace C:\Users\you\dosgames with the full path to your DOS games or applications folder.
After running the command you should see:
Drive C is mounted as local directory C:\Users\you\dosgames\
You can mount CD-ROM images, floppy disk images, and more. Use MOUNT -? to see all available options, or visit the Drive menu in the GUI menu bar.
4

Switch to the Mounted Drive

After mounting, switch to the new drive by typing its letter followed by a colon:
C:
The prompt will change to C:\>, showing you are now working inside your mounted folder.
5

Navigate to and Run a Program

Use standard DOS commands to navigate to your program and launch it:
DIR
Lists the contents of the current directory. Then navigate into a subfolder:
CD programname
Finally, run the program by typing its executable name (with or without the .EXE or .COM extension):
GAME.EXE
DOS is case-insensitive — game.exe, GAME.EXE, and Game.Exe all work the same way.
6

Unmount the Drive When Finished

When you are done, you can unmount the drive to release it:
MOUNT -u C
You can also simply close the DOSBox-X window to exit the emulator entirely.

​
Keyboard Shortcuts

DOSBox-X uses a host key for shortcuts that affect the emulator itself rather than the guest DOS system.
PlatformHost Key
WindowsF11
Linux / macOS / OtherF12
ShortcutAction
Host + FToggle fullscreen mode
Host + PausePause / resume emulation
Ctrl + F10Unlock / lock the mouse cursor
Alt + PauseBreak into the built-in debugger
Alt + F12 (Mac)Break into the built-in debugger
You can reassign the host key and all other shortcuts using the DOSBox-X mapper editor. Open it from Main → Mapper editor in the GUI menu bar, or press Host + M.

​
Using the GUI Menu Bar

DOSBox-X includes a drop-down menu bar at the top of the window — a major feature not found in the original DOSBox. You can use it to:
  • Mount and unmount drives — via the Drive menu
  • Change machine and video settings — via the Video menu
  • Control emulation speed and CPU type — via the CPU menu
  • Save and load states — via the Main menu (up to 100 save slots)
  • Open the graphical configuration tool — via Main → Configuration tool
  • Capture screenshots or video — via the Capture menu
If the menu bar is not visible, you can toggle it with the showmenu option in the [sdl] section of your config file, or by pressing Host + Escape.

​
Sample Minimal Configuration File

Here is the sample dosbox-x.conf shown earlier, with comments explaining each setting: 
[dosbox]
# Machine type to emulate. svga_s3 is a good general-purpose choice.
machine = svga_s3
# Amount of RAM in MB (1–384). 16 MB covers most DOS-era software.
memsize = 16

[render]
# Video output method. opengl gives smooth, hardware-accelerated output.
output = opengl
# Maintain the correct 4:3 aspect ratio of original DOS display.
aspect = true

[autoexec]
# Commands here run automatically when DOSBox-X starts.
# Mount your DOS software folder as drive C:
mount c ~/dosgames
# Switch to drive C: immediately on startup.
c:
ValueUse Case
pc98NEC PC-98 Japanese DOS software
cgaVery early CGA-only DOS games
tandyTandy 1000 games with enhanced graphics and sound
svga_s3General purpose — most DOS games and applications
vgaonlyWindows 3.x and standard VGA software
svga_et4000Some specific SVGA-dependent titles

​
Next Steps

Now that you have DOSBox-X running and a program launched, explore these resources to get the most out of your setup:

DOSBox-X Wiki

Comprehensive documentation covering configuration, per-game tips, Windows 9x setup, and more.

Configuration Reference

Full documentation of every configuration option available in dosbox-x.conf.

Feature Highlights

Deep-dive overview of DOSBox-X’s unique features compared to standard DOSBox.

Issue Tracker

Report bugs or compatibility issues, or search for known workarounds.

Build docs developers (and LLMs) love

Get started for freeTalk to us