--- name: "dosbox-x" section: "1" platform: "linux" package: "dosbox-x" version: "2025.02.01+dfsg-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/dosbox-x" --- # dosbox-x(1) a x86/DOS and PC98 emulator ## NAME dosbox-x - a x86/DOS and PC98 emulator ## SYNOPSIS **dosbox-x** \[*OPTIONS*\] \[*FILE*\] ## DESCRIPTION This manual page briefly documents DOSBox-X, an x86/DOS and PC98 emulator. Options are listed below. Depending on the option, one or more may be specified. The optional *FILE* argument should be a DOS executable or a directory. If it is a DOS executable (.com .exe .bat), the program will run automatically. If it is a directory, the directory specified will be mounted as the C:\\ drive. If the DOS executable requires parameters, enclose the command and it’s parameters in quotes. For an introduction type *INTRO* inside dosbox-x. ## OPTIONS A summary of available options. - **-?**, **-h** or **-help** Display the help screen and exit. - **-v**, **-ver** or **-version** Display the version information and exit. - **-fullscreen**, **-fs** Start dosbox-x in fullscreen mode. - **-machine** *machinetype* Start dosbox-x with a specific machine type. Valid choices are: • **mda** IBM Monochrome Display Adapter (text only) • **hercules** Hercules Graphics Card (monochrome) • **cga** IBM Color Graphics Adapter, with automatic RGB/Composite switching. • **cga\_mono** IBM CGA attached to a monochrome display • **cga\_rgb** IBM CGA attached to an RGB monitor • **cga\_composite** IBM CGA (early revision) attached to an NTSC TV • **cga\_composite2** IBM CGA (late revision) attached to an NTSC TV • **pcjr** IBM PCjr • **pcjr\_composite** IBM PCjr (late revision) attached to NTSC TV • **pcjr\_composite2** IBM PCjr (late revision) attached to NTSC TV • **tandy** Tandy 1000 Graphics Adapter • **amstrad** Amstrad PC1512 graphics mode • **ega** IBM Enhanced Graphics Adapter • **jega** Japanese Enhanced Graphics Adapter (Microsoft AX) • **mcga** IBM Multi-Color Graphics Array • **vgaonly** IBM Video Graphics Array (see below) • **svga\_paradise** SVGA - Paradise Systems PVGA1A • **svga\_et3000** SVGA - Tseng Labs ET3000 • **svga\_et4000** SVGA - Tseng Labs ET4000 • **svga\_s3** VESA SVGA - S3 Trio64 - VBE 2.0 • **svga\_s386c928** VESA SVGA - S3 86c928 - VBE 2.0 (experimental) • **svga\_s3vision864** VESA SVGA - S3 Vision 864 - VBE 2.0 • **svga\_s3vision868** VESA SVGA - S3 Vision 868 - VBE 2.0 • **svga\_s3vision964** VESA SVGA - S3 Vision 964 - VBE 2.0 • **svga\_s3vision968** VESA SVGA - S3 Vision 968 - VBE 2.0 • **svga\_s3trio32** VESA SVGA - S3 Trio32 - VBE 2.0 • **svga\_s3trio64** VESA SVGA - S3 Trio64 - VBE 2.0 (same as **svga\_s3**) • **svga\_s3trio64v+** VESA SVGA - S3 Trio64V+ - VBE 2.0 • **svga\_s3virge** VESA SVGA - S3 ViRGE - VBE 2.0 (experimental) • **svga\_s3virgevx** VESA SVGA - S3 ViRGE VX - VBE 2.0 (experimental) • **vesa\_oldvbe** VESA SVGA - S3 Trio64 with VESA BIOS Extensions (VBE) 1.2 • **vesa\_oldvbe10** VESA SVGA - S3 Trio64 with VESA BIOS Extensions (VBE) 1.0 • **vesa\_nolfb** VESA SVGA - S3 Trio64 with VBE 2.0 with Linear Frame Buffer disabled • **pc98** Japanese NEC PC-98 emulation • **pc9801** same as **pc98** • **pc9821** same as **pc98** • **fm\_towns** Japanese Fujitsu FM Towns (not implemented) The default is **svga\_s3**. For some special VGA effects the machinetype **vgaonly** can be used, note that this disables SVGA capabilities and might be slower due to the higher emulation accuracy. **Note**\ The *machinetype* affects not only the emulated video card, but may also effect the available sound cards. - **-conf** *configfile* Start dosbox-x with the options specified in *configfile*. This file may also have a section called *\[autoexec\]* in which you can put commands you wish to execute on startup. Multiple **-conf** options with *configfiles* can be specified and they will be overlaid on each other. - **-editconf** \[*editor*\] Open the default configuration file in a text editor. If no editor name is given, then use the program from the EDITOR environment variable. - **-userconf** Load the configuration file located in ~/.config/dosbox-x. Can be combined with the **-conf** option. - **-printconf** Prints the location of the default configuration file and exit. - **-eraseconf**, **-resetconf** Removes the default configuration file and exit. - **-erasemapper**, **-resetmapper** Removes the mapperfile configured in the clean default configuration file and exit. - **-opencaptures** *program* Calls program with as first parameter the location of the captures folder and exit. - **-opensaves** *program* Calls program with as first parameter the location of the saves folder and exit. - **-startui**, **-startgui** or **-starttool** Start DOSBox-X with GUI configuration tool. - **-startmapper** Start the internal keymapper on startup of dosbox-x. You can use it to change the keys dosbox-x uses. - **-promptfolder** Prompt for the working directory when DOSBox-X starts. - **-nopromptfolder** Do not prompt for the working directory when DOSBox-X starts. - **-nogui** or **-nomenu** Do not show the GUI menu bar when in windowed mode. - **-showcycles** Show cycles count (FPS) in the title. - **-showrt** Show emulation speed relative to realtime in the title. - **-socket** *socketnumber* Passes the TCP socket number *socketnumber* for the nullmodem emulation. See the WIKI for details. - **-savedir** *path* Set path for the save slots. - **-defaultdir** *path* Set the default working path for DOSBox-X. - **-defaultconf** Use the default config settings for DOSBox-X. - **-defaultmapper** Use the default key mappings for DOSBox-X. - **-data-host-forced** Force synchronization of date and time with the host. - **-display2** \[*color*\] Enable both standard & monochrome dual-screen mode. The monochrome display defaults to white, but can optionally be set to *green* or *amber*. - **-lang** *message\_file* Start dosbox-x with the language specified in *message\_file*. - **-nodpiaware** Ignore (do not signal) Windows DPI awareness. - **-securemode** Enable secure mode, which is meant to prevent a DOS program potentially gaining access to files outside directories mounted in the \[autoexec\] section of the config file. It does this by running **Z:\\SYSTEM\\CONFIG.COM -securemode** after completing the \[autoexec\] section (which in turn disables any changes to how the drives are mounted "inside" dosbox-x). It also disables various other CONFIG.COM options that could be exploited. - **-prerun** If *FILE* is given, run it before the AUTOEXEC.BAT config section - **-hostrun** Enable START command, CLIP$ device and long filename (LFN) support - **-noconfig** Skips the \[config\] section of the loaded configuration file. This is equivalent to skipping CONFIG.SYS in DOS. - **-noautoexec** Skips the \[autoexec\] section of the loaded configuration file. This is equivalent to skipping AUTOEXEC.BAT in DOS. - **-exit** dosbox-x will close itself when the DOS program specified by *FILE* ends. - **-silent** Run DOSBox-X silently and exit after executing the \[autoexec\] section of the loaded config file. - **-o** *option(s)* Provide command-line option(s) for \[*FILE*\] if specified. - **-c** *command* Runs the specified command before running \[*FILE*\]. Multiple commands can be specified. Each command should start with **-c** though. A command can be an Internal Program, a DOS command or an executable on a mounted drive. If the command requires parameters, enclose the command and its parameters in quotes. **-set** *section property=value* Set the config option (override any config file). If the property contains spaces, ensure to enclose the string in quotes. The section is the name of a dosbox-x config section such as **\[video\]** without the brackets. Multiple **-set** commands may be specified. If a property is unique, the section may be omitted. e.g. **-set sdl output=ttf** is equivalent to **-set output=ttf** - **-time-limit** *seconds* Kill the emulator after *seconds*. - **-fastlaunch** Fast launch mode (skip the BIOS logo and welcome banner). - **-helpdebug** Show debug-related options and exit. ## INTERNAL INTERPRETER COMMANDS **dosbox-x** Supports most of the internal DOS commands found in COMMAND.COM. Help text is integrated for these commands in DOSBox-X, and will not be duplicated here. An explanation of these commands can also be found on the DOSBox-X wiki on the Supported Commands page. **ALIAS**, **ATTRIB**, **BREAK**, **CALL**, **CD**/**CDDIR**, **CHCP**, **CHOICE**, **CLS**, **COPY**, **COUNTRY**, **CTTY**, **DATE**, **DEL**/**ERASE**, **DELTREE**, **ECHO**, **EXIT**, **DIR**, **FOR**, **GOTO**, **HELP**, **IF**, **LFNFOR**, **LH**/**LOADHIGH**, **MD**/**MKDIR**, **MORE**, **PATH**, **PAUSE**, **PROMPT**, **RD**/**RMDIR**, **REM**, **REN**/**RENAME**, **SET**, **SHIFT**, **SUBST**, **TIME**, **TRUENAME**, **TYPE**, **VER**, **VERIFY**, **VOL** ## OTHER PROVIDED COMMANDS In addition, the following extra commands are available on the emulated Z: drive: **Note**\ Some commands (like NE2000) are only present in case the corresponding feature is enabled. • **Z:\\4DOS** **4DOS**, **4HELP**, **OPTION**, **BATCOMP** • **Z:\\BIN** **EVAL**, **SHUTDOWN**, **DSXMENU**, **CWSDPMI**, **EMSMAGIC**, **UNZIP**, **ZIP**, **MPXPLAY**, **DOSMID**, **CDPLAY**, **DOS4GW**, **DOS32A**, **DOSIDLE**, **UTF16**, **UTF8**, **AUTOTYPE**, **ADDKEY**, **LS**, **TITLE**, **COLOR**, **SETCOLOR** • **Z:\\DOS** **MEM**, **EDIT**, **PRINT**, **DISKCOPY**, **DEFRAG**, **FORMAT**, **FDISK**, **SYS**, **FC**, **COMP**, **CHKDSK**, **BUFFERS**, **DEVICE**, **APPEND**, **XCOPY**, **SORT**, **REPLACE**, **LASTDRIV**, **FILES**, **FCBS**, **FIND**, **MOVE**, **DEBUG**, **EDLIN**, **CHOICE**, **DELTREE**, **TREE**, **LABEL**, **LOADFIX**, **MOUSE**, **MODE**, **KEYB** • **Z:\\DEBUG** **HEXMEM32**, **HEXMEM16**, **A20GATE**, **BIOSTEST**, **INT2FDBG**, **NMITEST**, **LOADROM**, **VESAMOED**, **VFRCRATE** • **Z:\\SYSTEM** **PARALLEL**, **SERIAL**, **MIXER**, **CAPMOUSE**, **FLAGSAVE**, **CFGTOOL**, **RESCAN**, **RE-DOS**, **COUNTRY**, **CONFIG**, **BOOT**, **MOUNT**, **IMGSWAP**, **IMGMAKE**, **IMGMOUNT**, **INTRO**, **HELP**, **NE2000** • **Z:\\TEXTUTIL** **CGA**, **CLR**, **EGA**, **VGA**, **DCGA**, **132X25**, **132X43**, **132X50**, **132X60**, **80X25**, **80X50**, **80X60** ## SPECIAL KEYS **CTRL-F7** CGA emulation only - Switch between early and late model IBM CGA emulation. **CTRL-F8** CGA emulation only - Switch between Auto, RGBI and Composite monitor output emulation. **CTRL-SHIFT-F7** CGA emulation only - Decrease Hue **CTRL-SHIFT-F8** CGA emulation only - Increase Hue **CTRL-F7** CGA Mono and Hercules emulation only - Cycle between Green, Amber, White and Grey **CTRL-F8** CGA Mono and Hercules emulation only - Cycle between low and high brightness **F12-F** Switch between fullscreen and window mode. **F12-R** Reset the virtual machine inside DOSBox-X **F12-B** Reboot the emulated DOS (integrated DOS or guest DOS) inside DOSBox-X. **F12-C** Start DOSBox-X’s graphical configuration tool. **F12-M** Start DOSBox-X’s mapper editor. **F12-Esc** Show/hide DOSBox-X’s drop-down menu bar. **F12-Del** Send the selected special key combination (Ctrl+Alt+Del by default) to the guest system. **F12-{+}** Increase the sound volume of DOSBox-X’s emulated DOS. **F12-{-}** Decrease the sound volume of DOSBox-X’s emulated DOS. **F12-\]** Increase the emulated DOS’s current speed relative to real-time. **F12-\[** Decrease the emulated DOS’s current speed relative to real-time. **F12-{=}** Increase DOSBox-X’s emulation CPU cycles. **F12-{-}** Decrease DOSBox-X’s emulation CPU cycles. **F12-Up** Increase the font size for the TrueType font (TTF) output. **F12-Down** Decrease the font size for the TrueType font (TTF) output. **F12-Left** Reset the emulated DOS’s current CPU speed to the normal speed. **F12-Right** Toggle DOSBox-X’s speed lock. **F12-D** Swap between mounted CD images. **F12-O** Swap between mounted floppy images. **F12-P** Take a screenshot of the current screen in PNG format. **F12-I** Start/Stop capturing an AVI video of the current session. **F12-W** Start/Stop recording a WAV audio of the current session. Alt+Pause Start DOSBox-X’s Debugger. **F12-\[,\]** Select the previous save slot to save to or load from. **F12-\[.\]** Select the next save slot to save to or load from. **F12-S** Save current state to the selected save slot. **F12-L** Load the state from the selected save slot. **F12-Pause** Pause emulation (press again to continue). **Ctrl+F5** Copy all text on the DOS screen to the host clipboard. **Ctrl+F6** Paste the text in the host clipboard to the DOS screen. **Ctrl+F9** Exit DOSBox-X. **Ctrl+F10** Capture the mouse for use with the emulated DOS. These are the default keybindings. They can be changed in the keymapper. Saved/recorded files can be found in current\_directory/capture (can be changed in the configfile). The directory has to exist prior to starting dosbox-x else nothing gets saved or recorded! **Note**\ Once you increase your dosbox-x cycles beyond your computer’s maximum capacity, it will produce the same effect as slowing down the emulation. This maximum will vary from computer to computer, there is no standard. ## ENVIRONMENT Any configuration option can be overridden using an environment variable. Environment variables starting with prefix **DOSBOX** are processed and interpreted as follows: **DOSBOX\_SECTIONNAME\_PROPERTYNAME=value** For example, you can override the render aspect this way: **$ DOSBOX\_RENDER\_ASPECT=false dosbox-x** ## BUGS To report a bug, please visit \ ## RESOURCES **project web site:** \ **Project Wiki:** \ ## AUTHOR DOSBox-X is maintained by the DOSBox-X Team