DOSBox-X Integrated Debugger: Complete Reference Guide

DOSBox-X ships with a powerful integrated debugger that lets you inspect CPU registers, disassemble executing code, read and write arbitrary memory, set breakpoints, and monitor emulator log output — all without leaving the emulator. The debugger is built on top of the ncurses library and is displayed in the terminal window from which DOSBox-X was launched (or in a dedicated console on Windows). This guide explains how to access the debugger, navigate its interface, and use its command set to diagnose or reverse-engineer DOS programs.

The integrated debugger is only present in debug builds of DOSBox-X. Standard release binaries do not include it. To use the debugger, you must either compile DOSBox-X yourself with debug support enabled, or obtain a dedicated debug build. Check the DOSBox-X development builds page for debug-enabled binaries.

Opening the debugger

Windows
macOS
Linux

DOSBox-X automatically creates a console window when it starts. Once the emulator is running, press Alt+Pause to break into the debugger. The ncurses interface will appear in the console.

Launch DOSBox-X from a Terminal session — the debugger is drawn in that terminal window. Once running, press Alt+F12 to break into the debugger.

# Example — open Terminal, then run:
/Applications/DOSBox-X.app/Contents/MacOS/dosbox-x

Launch DOSBox-X from any terminal emulator. The debugger interface renders in that same terminal. Press Alt+Pause to break.

dosbox-x

The debugger interface is designed to scale and respond to terminal resize events, so you can widen or tall your terminal at any time.

On Linux and macOS, DOSBox-X must be started from a terminal for the debugger to function. Launching from a file manager or application menu will not provide the ncurses console the debugger needs.

Debugger interface windows

The debugger screen is divided into five named regions. Use Tab / Shift+Tab to move focus between them.

Register Overview

Always visible. Displays the current values of all general-purpose CPU registers (AX, BX, CX, DX, SI, DI, SP, BP), segment registers (CS, DS, ES, FS, GS, SS), instruction pointer (IP/EIP), and important CPU flags. Updates live as you step through instructions.

Code Overview

Shows disassembled x86 instructions at the current instruction pointer. Can be redirected to any address with the C command. Decoding respects the current CPU mode (real, protected, or long). Use this window to read code flow and identify the next instructions to execute.

Data View

Displays the raw bytes of memory at a chosen segment:offset, linear/virtual, or physical address. Two special values indicate inaccessible memory:

na — the segment does not exist, or the offset exceeds the segment’s limit (protected mode)
pf — the page is not present according to the page tables (paging enabled)

Press F8 to toggle printable ASCII character display alongside the hex bytes.

Output

A scrollable log of the last ~1,000 LOG() / LOG_MSG() messages emitted by the DOSBox-X codebase. When scrolled to the bottom, new messages appear automatically. Use PageUp / PageDown to scroll, and Home / End to jump to the very start or end of the buffer.

Variable

Not shown by default. Contains a user-defined list of named variables that can be loaded from a file with the LV command or inserted individually with IV. Useful for tracking specific memory locations by name during a debugging session.

The lowest row of the terminal is reserved for the command line — type debugger commands here and press Enter to execute them. An underscore marks the cursor position.

Launching a program under the debugger

The DEBUGBOX command, available inside the DOSBox-X DOS environment, provides two modes of operation:

REM Drop into the debugger immediately (no program):
DEBUGBOX

REM Launch a program and break at its entry point:
DEBUGBOX PROGRAM.EXE [arguments]

Breaking at the entry point means execution stops before the program’s first instruction runs, giving you a chance to inspect the initial register state, set additional breakpoints, or step through the loader sequence.

Keyboard shortcuts

All keyboard shortcuts are active when the debugger is open, regardless of which window has focus (except where navigation-specific).

Execution control
Navigation and history
Data view shortcuts

Key	Action
F5	Resume emulation (exit debugger, continue running)
F9	Set or clear a breakpoint at the address highlighted in the Code view
F10	Single-step over — executes the current instruction; does not trace into calls or interrupts
F11	Single-step into — executes the current instruction, tracing into calls and interrupts

Key	Action
Tab	Move focus to the next debugger window
Shift+Tab	Move focus to the previous debugger window
Up / Down	Scroll the focused window one line
PageUp	Scroll focused window up by one page
PageDown	Scroll focused window down by one page
Home	Jump to the top of the Output window
End	Jump to the bottom of the Output window
Insert	Toggle insert/overwrite mode in the command line
F3 / F6	Recall the previous command from history
F4 / F7	Recall the next command from history
Left / Right	Move the cursor within the command line

Key	Action
F8	Toggle printable-character display in the Data view
Alt+D	Point Data view to `DS:SI`
Alt+E	Point Data view to `ES:DI`
Alt+X	Point Data view to `DS:DX`
Alt+B	Point Data view to `ES:BX`
Alt+S	Point Data view to `SS:SP`

Debugger commands

Enter commands at the command line at the bottom of the debugger screen. Commands are not case-sensitive.

Breakpoints

Breakpoint commands

Command	Description
`BP <seg> <off>`	Add a real-mode breakpoint at segment:offset
`BPM <seg> <off>`	Add a breakpoint in protected mode at segment:offset
`BPPM <seg> <off>`	Add a memory-change breakpoint (protected mode) — triggers when memory at that address is written
`BPLM <offset>`	Add a breakpoint at a linear/virtual address
`BPINT <intnum>`	Break when interrupt `intnum` is called
`BPINT <intnum> <AH>`	Break when interrupt `intnum` is called with `AH` equal to the specified value
`BPLIST`	List all current breakpoints with their indices
`BPDEL <num>`	Delete the breakpoint with the given index (from `BPLIST`)

Example — break on INT 21h function 4Bh (DOS EXEC):

BPINT 21 4B

Execution

Execution commands

Command	Description
`RUN`	Resume emulation (same as pressing F5)
`RUNWATCH`	Resume emulation while continuously displaying CPU state in the output window

Navigating views

View navigation commands

Command	Description
`C <seg> <off>`	Set the Code view to display code at the given segment:offset
`D <seg> <off>`	Set the Data view to a segment:offset address
`DV <offset>`	Set the Data view to a linear/virtual address
`DP <offset>`	Set the Data view to a physical memory address (bypasses paging)
`INTHAND <intnum>`	Set the Code view to the start of the handler for interrupt `intnum`
`VRD`	Force a redraw of the video output

Reading and writing state

Command	Description
`SR <reg> <value>`	Set register `reg` to `value` (e.g., `SR AX 1234`)
`EV <value>`	Evaluate and display a register or expression value
`SM <seg> <off> [bytes…]`	Write raw hex bytes to memory at segment:offset
`SMV <offset> [bytes…]`	Write raw hex bytes to a linear/virtual address
`FM <seg> <off>`	Freeze (lock) the memory value at segment:offset so it cannot be changed by the guest
`A20`	Show the current A20 gate state
`A20 ON` / `A20 OFF`	Enable or disable the A20 gate

Memory search and dump

Memory search and dump commands

Command	Description
`MEMDUMP <seg> <off> <count>`	Dump `count` bytes from segment:offset to `MEMDUMP.TXT`
`MEMDUMPBIN <seg> <off> <count>`	Dump `count` bytes to `MEMDUMP.BIN` (raw binary)
`MEMFIND <seg> <off> [bytes…]`	Start a memory-search instance at the given address
`MEMS <operator> <value>`	Search for a value within an active `MEMFIND` instance

Example — dump the first 256 bytes of the DOS PSP (typically at 0000:0000):

MEMDUMP 0000 0000 100

CPU logging

CPU logging commands

Command	Description
`LOG <count>`	Log `count` (hexadecimal) CPU instructions to `LOGCPU.TXT` with standard detail
`LOGS <count>`	Short-format CPU log to `LOGCPU.TXT`
`LOGL <count>`	Long-format CPU log to `LOGCPU.TXT`
`LOGC <count>`	Log only the `CS:IP` values for `count` instructions
`ADDLOG <message>`	Insert a custom text message into the CPU log file
`HEAVYLOG`	Toggle heavy CPU logging (generates very large log files; use sparingly)

Interrupt and I/O inspection

Interrupt and I/O commands

Command	Description
`INTT <intnum>`	Trace an interrupt (step into it)
`INT <intnum>`	Trigger an interrupt
`INTVEC <file>`	Dump the full interrupt vector table (IVT) to `file`
`CALLBACKS`	Display a list of all registered DOSBox-X callback handlers
`INP <port>`	Read a byte from I/O port `port`
`INW <port>`	Read a word from I/O port `port`
`IND <port>`	Read a dword from I/O port `port`
`OUTP <port> <data>`	Write a byte to I/O port `port`
`OUTW <port> <data>`	Write a word to I/O port
`OUTD <port> <data>`	Write a dword to I/O port
`PIC`	Show interrupt controller (8259 PIC) state
`PIC MASKIRQ <irq>`	Mask an IRQ at the PIC
`PIC UNMASKIRQ <irq>`	Unmask an IRQ at the PIC
`PIC ACKIRQ <irq>`	Acknowledge an IRQ at the interrupt controller
`PIC RAISEIRQ <irq>`	Manually assert an IRQ signal
`PIC LOWERIRQ <irq>`	Manually deassert an IRQ signal

Descriptor tables and system structures

Protected-mode system commands

Command	Description
`GDT`	Dump the Global Descriptor Table
`LDT`	Dump the Local Descriptor Table
`IDT`	Dump the Interrupt Descriptor Table
`PAGING`	Dump page table information (only meaningful when paging is enabled)
`SELINFO <n>`	Show detailed information for selector `n`
`CPU`	Dump extended CPU information
`FPU`	Dump FPU register and status information
`MMX [=t] <reg> [SET <val>]`	Display or set MMX registers (types: B, W, D, Q)
`SSE [=t] <reg> [SET <val>]`	Display or set SSE registers (types: B, W, D, Q, X, S, F)

DOS memory and subsystem inspection

DOS subsystem commands

Command	Description
`DOS MCBS`	Dump the DOS MCB (Memory Control Block) chain — shows conventional memory allocations
`DOS KERN`	Dump the DOS kernel memory allocation list
`DOS XMS`	Dump the XMS (extended memory) allocation list
`DOS EMS`	Dump the EMS (expanded memory) allocation list
`DOS FNKEY`	Dump PC-98 function key (FnKey) mapping (PC-98 mode only)
`BIOS MEM`	Dump the BIOS memory allocation and layout
`EMU MEM`	Show emulator memory information
`EMU MACHINE`	Show emulated machine information
`VGA <cmd>`	VGA-related debugging commands
`PC98 <cmd>`	PC-98-related debugging commands

Variables

Variable commands

Command	Description
`IV <seg> <off> <name>`	Insert a named variable pointing to segment:offset
`SV <name>`	Save the current variable list to file `name`
`LV <name>`	Load a variable list from file `name`

Window layout

Window layout commands

Command	Description
`MOVEWINDN`	Move the currently focused window down
`MOVEWINUP`	Move the currently focused window up
`SHOWWIN <name>`	Show a hidden window (e.g., `SHOWWIN VARIABLE`)
`HIDEWIN <name>`	Hide a visible window

Miscellaneous

Miscellaneous commands

Command	Description
`EXTEND`	Toggle additional CPU register display in the Register Overview
`TIMERIRQ`	Manually fire the timer IRQ
`VRT`	Resume emulation and break at the next vertical retrace
`TIME [time]`	Display or override the emulated system time
`DATE [date]`	Display or override the emulated system date
`ZEROPROTECT`	Toggle zero-page write protection
`HELP`	Show a brief command reference in the Output window

The Output window

The Output window shows a rolling buffer of the last ~1,000 log messages produced by LOG() and LOG_MSG() calls throughout the DOSBox-X source code. This includes device initialization messages, DOS function call traces (when heavy logging is on), and any messages added with ADDLOG.

Scroll to the latest messages

Press End (or Fn+Right on Mac) to jump to the bottom of the Output window and see the most recent log messages.

Scroll through history

Press PageUp and PageDown to move through the buffer in page-sized increments, or Up / Down for single-line scrolling.

Enable heavy logging for detailed traces

Type HEAVYLOG at the command line and press Enter. This enables verbose per-instruction CPU logging. The Output window will fill quickly — use this only for short execution windows.

Dump the log to a file

Use LOG <count> to write the CPU execution trace to LOGCPU.TXT on the host filesystem, where you can examine it with any text editor.

Keep the Output window scrolled to the bottom (press End) during normal debugging sessions so that new messages appear as they are generated. Scroll up only when you need to review earlier output.

Getting Started

Configuration

Drives & Storage

Emulation Features

Troubleshooting

DOSBox-X Integrated Debugger: Complete Reference Guide

Opening the debugger

Debugger interface windows

Register Overview

Code Overview

Data View

Output

Variable

Launching a program under the debugger

Keyboard shortcuts

Debugger commands

Breakpoints

Execution

Navigating views

Reading and writing state

Memory search and dump

CPU logging

Interrupt and I/O inspection

Descriptor tables and system structures

DOS memory and subsystem inspection

Variables

Window layout

Miscellaneous

The Output window

Build docs developers (and LLMs) love

Getting Started

Configuration

Drives & Storage

Emulation Features

Troubleshooting

Documentation Index

​Opening the debugger

​Debugger interface windows

Register Overview

Code Overview

Data View

Output

Variable

​Launching a program under the debugger

​Keyboard shortcuts

​Debugger commands

​Breakpoints

​Execution

​Navigating views

​Reading and writing state

​Memory search and dump

​CPU logging

​Interrupt and I/O inspection

​Descriptor tables and system structures

​DOS memory and subsystem inspection

​Variables

​Window layout

​Miscellaneous

​The Output window

Build docs developers (and LLMs) love

Opening the debugger

Debugger interface windows

Launching a program under the debugger

Keyboard shortcuts

Debugger commands

Breakpoints

Execution

Navigating views

Reading and writing state

Memory search and dump

CPU logging

Interrupt and I/O inspection

Descriptor tables and system structures

DOS memory and subsystem inspection

Variables

Window layout

Miscellaneous

The Output window