DOS Environment and Peripheral Settings in DOSBox-X

Beyond the video and audio hardware, DOSBox-X emulates the full DOS software environment: memory managers, the keyboard and mouse driver stack, joystick hardware, serial and parallel ports, and the CONFIG.SYS equivalent. The [dos] section is the most important of these, controlling memory architecture and DOS version compatibility. The [keyboard], [joystick], [serial], and [parallel] sections let you attach virtual peripherals, while [config] and [autoexec] reproduce the CONFIG.SYS and AUTOEXEC.BAT that DOS normally reads on boot.

`[dos]` — DOS memory and environment

Extended and expanded memory

xms

bool

default:"true"

Enable XMS (eXtended Memory Specification) support. XMS allows DOS programs to access memory above the 640 KB conventional memory limit through a standardised interface (INT 2Fh, AH=43h). The vast majority of late-DOS applications and games require XMS.

xms = true

ems

string

default:"true"

Enable EMS (Expanded Memory Specification) support. EMS bank-switches extra memory into a 64 KB page frame in upper memory (typically at segment D000h).

Value	Behaviour
`true`	Enable EMS (best compatibility, default)
`emsboard`	Emulate a physical EMS board rather than a software driver
`emm386`	Emulate EMM386-style expanded memory under DPMI
`false`	Disable EMS entirely

Some programs conflict with EMS and require it to be disabled. If a program crashes on startup, try ems = false.

umb

bool

default:"true"

Enable UMB (Upper Memory Block) support. UMBs allow DOS device drivers and TSR programs to be loaded into the 384 KB region between 640 KB and 1 MB, freeing more conventional memory for games.

DOS version and compatibility

ver

string

default:""

Set the DOS version reported by DOSBox-X’s integrated DOS kernel. Many programs check the DOS version to decide which features to use.

Setting	Equivalent
(empty)	DOS 5.0 (default DOSBox-X behaviour)
`5.0`	MS-DOS 5.0 — recommended for gaming
`6.22`	MS-DOS 6.22
`7.0`	MS-DOS 7.0 / Windows 95 pure-DOS mode; enables LFN
`7.1`	MS-DOS 7.1 / Windows 98; enables FAT32 image support

ver = 7.1

lfn

string

default:"auto"

Enable long filename (LFN) support. With auto (default), LFN is activated when the reported DOS version is 7.0 or higher.Valid values: true, false, auto, autostart

Keyboard layout

keyboardlayout

string

default:"auto"

DOS keyboard layout code. Controls which character set and key-mapping is used for DOS text-mode input.Common layout codes:

Code	Language
`auto`	Detect from host OS locale (default)
`us`	United States
`uk`	United Kingdom
`de`	German
`fr`	French
`es`	Spanish
`it`	Italian
`none`	No layout — raw scan codes only

keyboardlayout = de

Disk I/O rate limiting

hard drive data rate limit

integer

default:"-1"

Limit hard disk I/O throughput in bytes per second. The default (-1) applies a reasonable emulated disk speed. Set to 0 to disable the limit and allow maximum speed (matching DOSBox SVN behaviour). Useful for games that timeout if the disk is too fast or too slow.

floppy drive data rate limit

integer

default:"-1"

Same as above but for floppy disk images. Default (-1) uses a realistic floppy speed. Set to 0 to remove the limit.

Report SHARE.EXE as resident and emulate file-locking and record-locking functions. Required for networked database applications such as dBASE and FoxPro that use DOS file-sharing APIs.

file access tries

integer

default:"0"

Number of times DOSBox-X retries a read/write/lock operation on mounted local drives before failing. Set this to a positive value (e.g. 3) when running networked DOS database applications to handle transient file-lock conflicts.

file access tries = 3

INT 33H mouse driver

int33

bool

default:"true"

Enable the INT 33H mouse driver. This is the standard DOS mouse API used by the vast majority of DOS games and applications. Disable only if you are running your own mouse driver inside DOSBox-X.

`[keyboard]` — Keyboard controller

aux

bool

default:"true"

Enable emulation of the 8042 AUX port (PS/2 mouse port). Required for PS/2 mouse emulation and for operating systems that do not use the BIOS to read mouse events (including Windows ME).

controllertype

string

default:"auto"

Type of keyboard controller to emulate.

Value	Controller
`auto`	Automatically match the `machine` type
`at`	AT-style PS/2 keyboard
`xt`	IBM PC/XT keyboard
`pcjr`	IBM PCjr keyboard (only with `machine=pcjr`)
`pc98`	PC-98 keyboard (only with `machine=pc98`)

auxdevice

string

default:"intellimouse"

Type of PS/2 mouse attached to the AUX port.

Value	Mouse type
`none`	No PS/2 mouse
`2button`	Standard 2-button PS/2 mouse
`3button`	3-button PS/2 mouse
`intellimouse`	Microsoft IntelliMouse (wheel + 3 buttons)
`intellimouse45`	IntelliMouse Explorer (5-button)

`[joystick]` — Joystick emulation

joysticktype

string

default:"auto"

Type of joystick interface to emulate.

Value	Description
`auto`	Auto-detect based on connected host joysticks (default)
`none`	Disable joystick emulation
`2axis`	Two independent 2-axis joysticks (two physical controllers)
`4axis`	One 4-axis joystick (uses first physical controller)
`4axis_2`	One 4-axis joystick (uses second physical controller)
`fcs`	Thrustmaster FCS flight stick
`ch`	CH Flightstick

joysticktype = 2axis

If you change joysticktype after saving a mapper file, reset the mapper (delete mapper-dosbox-x.map) to avoid stale axis/button assignments.

timed

bool

default:"true"

Enable timed intervals for joystick axis polling. Disable this if your joystick drifts or produces erratic readings; some older titles respond better without it.

autofire

bool

default:"false"

Continuously fire the first joystick button as long as it is held down, emulating a rapid-fire hardware feature.

swap34

bool

default:"false"

Swap the 3rd and 4th joystick axis. Useful for certain flight sticks where the throttle and rudder axes are in the wrong order.

buttonwrap

bool

default:"false"

Wrap button numbers back to zero after the maximum emulated button count is reached. Enable for games that read more buttons than the emulated type supports.

`[serial]` — Serial (COM) ports

DOSBox-X emulates up to nine serial ports (COM1–COM9). Each port is configured independently:

[serial]
serial1 = dummy
serial2 = modem listenport:5000
serial3 = nullmodem server:192.168.1.10 port:5001
serial4 = disabled

Available device types:

Type	Description
`disabled`	Port not present
`dummy`	Port exists but does nothing (default for COM1–COM2)
`file`	Capture serial output to a file
`modem`	Emulated Hayes modem (dial-up BBS access)
`nullmodem`	Virtual null-modem cable over TCP/UDP
`directserial`	Pass through to a real COM port on the host
`serialmouse`	Emulated serial mouse
`log`	Log raw serial data to the DOSBox-X log

Common parameters (append to the device type on the same line):

irq:N — Override the default IRQ
listenport:N — TCP port the modem listens on (modem)
server:host port:N — Remote host for nullmodem
realport:COMn — Host COM port for directserial

`[parallel]` — Parallel (LPT) ports

Up to nine parallel ports (LPT1–LPT9) can be configured. The most common use is attaching the virtual printer:

[parallel]
parallel1 = printer
parallel2 = disabled

Device types:

Type	Description
`disabled`	Port not present
`file`	Capture LPT output to a file
`printer`	Virtual dot-matrix printer (see `[printer]` section)
`reallpt`	Direct pass-through to a real parallel port
`disney`	Disney Sound Source attached to this port

`[config]` — DOS CONFIG.SYS equivalent

The [config] section mirrors a DOS CONFIG.SYS file. Most options here control the DOS kernel that DOSBox-X boots:

[config]
rem    = This section acts as CONFIG.SYS
dos    = high, umb
files  = 30
fcbs   = 0
shell  =
break  = off

Option	Description
`dos`	`high` loads DOS into HMA; `umb` enables upper memory
`files`	Number of file handles available to DOS programs (8–255; `0` = auto)
`fcbs`	Number of FCB handles (1–255; `0` = auto)
`shell`	Alternative command shell (e.g. `Z:\4DOS\4DOS.COM`)
`break`	Extended Ctrl+C checking (`on` or `off`)
`numlock`	Initial NumLock state (`on` or `off`)
`country`	Country code for date/time formats and code page
`lastdrive`	Highest drive letter accessible (A–Z)

`[autoexec]` — Startup commands

Every line in the [autoexec] section is executed as a DOS command when DOSBox-X finishes its startup sequence, exactly like AUTOEXEC.BAT on a real DOS machine. Use this section to mount drives, configure the PATH, and optionally launch a game automatically.

[autoexec]
# Mount the host games folder as drive C:
mount c ~/dosgames

# Mount a CD-ROM image
imgmount d ~/isos/game.iso -t iso

# Change to drive C and navigate to the game
c:
cd ultm

# Launch automatically (comment this out to land at a DOS prompt)
# ultima7.exe

Leave the auto-launch line commented out while setting up a game. Once everything works correctly, uncomment it for a seamless experience where DOSBox-X boots straight into the game.

Useful autoexec commands

Command	Purpose
`mount c ~/folder`	Mount a host directory as a DOS drive
`mount c image.img`	Mount a floppy or hard disk image
`imgmount d game.iso -t iso`	Mount a CD-ROM image as drive D:
`set PATH=C:\;C:\GAME`	Add directories to the PATH
`set BLASTER=A220 I7 D1 H5 T6`	Manually set the BLASTER environment variable
`loadhigh program.exe`	Load a TSR into upper memory
`keyb de`	Load a keyboard layout at startup

The built-in CONFIG command

The CONFIG command lets you read and write configuration settings at the DOSBox-X command prompt while the emulator is running. Changes take effect immediately where supported.

REM Read the current value of a setting
CONFIG -get dos xms

REM Set a value at runtime
CONFIG -set dos ems false
CONFIG -set cpu cycles fixed 25000

REM Write only changed settings to a file
CONFIG -wc c:\myconfig.conf

REM Full form (equivalent to -wc)
CONFIG -writeconf c:\myconfig.conf

REM Write ALL options including advanced/hidden ones
CONFIG -all -wc c:\fullconfig.conf

CONFIG -all -wc produces a complete configuration file equivalent to dosbox-x.reference.full.conf. This is the recommended way to generate a starting point for customisation from within a running DOSBox-X session.

Complete DOS environment example

The following snippet shows a typical configuration for a well-behaved late-DOS gaming environment with network database support:

[dos]
xms                      = true
ems                      = true
umb                      = true
ver                      = 6.22
keyboardlayout           = us
share                    = true
file access tries        = 3
hard drive data rate limit = -1
int33                    = true

[keyboard]
aux        = true
auxdevice  = intellimouse

[joystick]
joysticktype = 2axis
timed        = true

[serial]
serial1 = dummy
serial2 = disabled

[parallel]
parallel1 = printer

[config]
dos      = high, umb
files    = 30
break    = off

[autoexec]
mount c ~/dosgames
c:

Getting Started

Configuration

Drives & Storage

Emulation Features

Troubleshooting

DOS Environment and Peripheral Settings in DOSBox-X

`[dos]` — DOS memory and environment

Extended and expanded memory

DOS version and compatibility

Keyboard layout

Disk I/O rate limiting

INT 33H mouse driver

`[keyboard]` — Keyboard controller

`[joystick]` — Joystick emulation

`[serial]` — Serial (COM) ports

`[parallel]` — Parallel (LPT) ports

`[config]` — DOS CONFIG.SYS equivalent

`[autoexec]` — Startup commands

Useful autoexec commands

The built-in CONFIG command

Complete DOS environment example

Build docs developers (and LLMs) love

Getting Started

Configuration

Drives & Storage

Emulation Features

Troubleshooting

Documentation Index

​[dos] — DOS memory and environment

​Extended and expanded memory

​DOS version and compatibility

​Keyboard layout

​Disk I/O rate limiting

​File access and sharing

​INT 33H mouse driver

​[keyboard] — Keyboard controller

​[joystick] — Joystick emulation

​[serial] — Serial (COM) ports

​[parallel] — Parallel (LPT) ports

​[config] — DOS CONFIG.SYS equivalent

​[autoexec] — Startup commands

​Useful autoexec commands

​The built-in CONFIG command

​Complete DOS environment example

Build docs developers (and LLMs) love

`[dos]` — DOS memory and environment

Extended and expanded memory

DOS version and compatibility

Keyboard layout

Disk I/O rate limiting

File access and sharing

INT 33H mouse driver

`[keyboard]` — Keyboard controller

`[joystick]` — Joystick emulation

`[serial]` — Serial (COM) ports

`[parallel]` — Parallel (LPT) ports

`[config]` — DOS CONFIG.SYS equivalent

`[autoexec]` — Startup commands

Useful autoexec commands

The built-in CONFIG command

Complete DOS environment example