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 includes a comprehensive save and load state system that snapshots the complete emulator state — CPU registers, memory contents, hardware state, and the current program — to a file that can be restored at any time. This feature goes well beyond what original DOS hardware could offer, making it easy to create checkpoints before a difficult section of a game, quickly switch between projects, or preserve a session for later without shutting down. Up to 100 numbered save slots are available, and you can also save to arbitrary file paths.

​
Saving and Loading States

​
Using Keyboard Shortcuts

The fastest way to save and load is with host-key shortcuts. The host key defaults to F11 on Windows and F12 on Linux and macOS (or whichever key is assigned in the mapper).
ActionShortcut
Save to current slotHost key + S
Load from current slotHost key + L
Previous save slotHost key + , (comma)
Next save slotHost key + . (period)

​
Using the Menu

You can also access save and load operations through the Main menu:
  • Main → Save State — saves to the currently selected slot
  • Main → Load State — loads from the currently selected slot
  • Main → Select Save Slot — choose which of the 100 slots is active
The menu approach is useful when you want to explicitly pick a slot before saving or loading, without changing the default slot permanently in your configuration.

​
Configuration Options

All save-state settings live in the [dosbox] section of your configuration file. 
[dosbox]
saveslot      = 1
savefile      =
saveremark    = true
forceloadstate = false
autosave      =
OptionDefaultDescription
saveslot1Default save slot number (1–100). This is the slot used by the host key shortcuts and menu save/load actions
savefile(empty)Path to a specific save file. When set, this file is used instead of a numbered slot
saveremarktrueWhen saving, prompt the user to enter a text remark or note to annotate the save state
forceloadstatefalseIf true, load a saved state even when DOSBox-X detects a mismatch in version, machine type, program name, or memory size
autosave(empty)Auto-save configuration string (see below)

​
Auto-Save

The autosave option enables periodic background saving without any user interaction. It is configured with a compact string syntax that lets you set the interval, the range of slots to rotate through, and optionally override the slot range for specific programs.

​
Syntax

autosave = <interval> [<slot-or-range>] [PROGRAM:<slot-or-range> ...]
  • <interval>: Seconds between saves. Prefix with - to configure auto-save without starting it immediately.
  • <slot-or-range>: A single slot number (e.g. 5) or a range (e.g. 1-20). Saves rotate through the range.
  • PROGRAM:<slot-or-range>: Override slot range when a specific program name is running. Up to 9 program overrides are supported.

​
Examples

autosave = 30 1-20
DOSBox-X saves to slot 1, then slot 2, and so on up to slot 20, then wraps back to slot 1. A new auto-save fires every 30 seconds.
autosave = 10 11-20 DOOM:21-30 EDIT:31
  • Every 10 seconds, save to slots 11–20 by default
  • While DOOM.EXE is running, save to slots 21–30 instead
  • While EDIT.COM is running, always save to slot 31
autosave = -60 1-10
The leading - means DOSBox-X sets up the 60-second auto-save configuration but does not begin saving automatically when it starts. You can activate it later from the menu.
Auto-save uses the same slot files as manual saves. If you auto-save to a slot you also use for manual saves, the auto-save will overwrite it on the next interval.

​
Save File Locations

Numbered save slots (1–100) are stored in DOSBox-X’s default save directory, which is determined by the platform:
PlatformDefault save directory
Windows%APPDATA%\DOSBox-X\
Linux~/.config/dosbox-x/
macOS~/Library/Application Support/dosbox-x/
Slot files are named in the format dosbox-x.sav01 through dosbox-x.sav100 (zero-padded).To override the save directory for all slots, launch DOSBox-X with the -savedir command-line option:
dosbox-x -savedir /path/to/my/saves

​
Compatibility and Version Matching

Save states encode the DOSBox-X version, machine type, and memory size at the time of saving. When loading, DOSBox-X checks that these match the current configuration.
Loading a save state created with a different DOSBox-X version, different machine type, or different memsize will normally fail with a mismatch error. This is a safety measure to prevent crashes from incompatible state data.
To override the compatibility check and force-load a save state regardless of mismatches: 
[dosbox]
forceloadstate = true
You can also toggle forceloadstate from the Main menu without editing the configuration file. Use this option carefully — loading an incompatible state may cause emulation instability or crashes.

​
Remarks and Annotations

When saveremark = true, DOSBox-X displays a text input dialog each time you save a state, allowing you to type a short note such as “Before final boss” or “Chapter 3 start”. These remarks are stored inside the save file and displayed in the slot selector, making it easy to identify saves when you have many slots in use. To skip the remark prompt and save silently, set: 
[dosbox]
saveremark = false

​
Tips and Best Practices

Use slot ranges for auto-save

Assigning a range (e.g. autosave = 30 81-100) dedicates slots 81–100 to auto-saves, leaving slots 1–80 free for manual checkpoints. This prevents auto-saves from overwriting your deliberate saves.

Save before risky operations

Save to a manual slot before attempting something that might crash the guest OS (such as installing a driver in Windows 9x or running an untested program). You can restore the working state instantly if things go wrong.

Keep versions in sync

If you update DOSBox-X, existing save states from older versions may not load without forceloadstate. Back up your save files before upgrading if you have long-running sessions you want to preserve.

Use savefile for portable saves

Setting savefile to a path inside your game directory keeps the save state co-located with the disk image, making it easier to archive or share a complete emulated environment.

Build docs developers (and LLMs) love

Get started for freeTalk to us