Batch Mode

Running Dolphin in headless mode for automation and testing

Batch mode allows you to run Dolphin without the graphical user interface, making it ideal for automation, continuous integration, testing, and scripted workflows.

Overview

Batch mode (--batch or -b) runs Dolphin headless, without displaying the main window. The emulation runs in the background, and Dolphin exits automatically when the game stops or an error occurs.

Requirements

Batch mode requires one of:

• --exec - Execute a game file
• --nand-title - Launch a NAND title

Without specifying what to run, batch mode will fail.

Basic Usage

dolphin-emu --batch --exec=/path/to/game.iso

Common Use Cases

Automated Testing

Run games automatically to completion:

#!/bin/bash
for game in /games/*.iso; do
  echo "Testing $game"
  dolphin-emu --batch --exec="$game"
  echo "Exit code: $?"
done

TAS (Tool-Assisted Speedrun) Playback

Play back input recordings without GUI:

dolphin-emu \
  --batch \
  --exec=game.iso \
  --movie=worldrecord.dtm

Save State Loading

Start from a specific save state:

dolphin-emu \
  --batch \
  --exec=game.iso \
  --save_state=checkpoint.sav

Configuration Testing

Test different emulation settings:

dolphin-emu \
  --batch \
  --exec=game.iso \
  --config=Core.CPUCore=1 \
  --config=Core.Overclock=2.0

Continuous Integration

Run regression tests in CI/CD pipelines:

# .github/workflows/test.yml
name: Emulation Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Run game test
        run: |
          dolphin-emu \
            --batch \
            --exec=test-rom.iso \
            --config=Core.CPUCore=1

Configuration in Batch Mode

You can override configuration settings using --config:

dolphin-emu \
  --batch \
  --exec=game.iso \
  --config=Core.CPUCore=1 \
  --config=Core.SyncOnSkipIdle=False \
  --video_backend=Null

Useful Batch Mode Configurations

# Disable framelimit for faster-than-realtime execution
--config=Core.Framelimit=0

# Use CPU core interpreter for determinism
--config=Core.CPUCore=0

# Disable audio
--config=DSP.Backend=No audio output

# Use null video backend (no rendering)
--video_backend=Null

Video Backends for Batch Mode

Null Backend (No Rendering)

Fastest option, no graphics output:

dolphin-emu \
  --batch \
  --exec=game.iso \
  --video_backend=Null

Software Renderer (For Testing)

CPU-based rendering, deterministic:

dolphin-emu \
  --batch \
  --exec=game.iso \
  --video_backend="Software Renderer"

Hardware Backends (With Display Server)

On Linux servers without a display, use xvfb-run:

xvfb-run dolphin-emu \
  --batch \
  --exec=game.iso \
  --video_backend=Vulkan

Exit Behavior

Dolphin exits automatically when:

• The game stops
• An error occurs
• The movie playback completes
• The emulation crashes

Check the exit code to determine success:

dolphin-emu --batch --exec=game.iso
if [ $? -eq 0 ]; then
  echo "Success"
else
  echo "Failed with code $?"
fi

Logging

Enable logging to capture output:

dolphin-emu \
  --batch \
  --logger \
  --exec=game.iso 2>&1 | tee dolphin.log

User Directory

Use isolated user directories for parallel execution:

# Test 1
dolphin-emu \
  --batch \
  --user=/tmp/dolphin-test1 \
  --exec=game1.iso &

# Test 2
dolphin-emu \
  --batch \
  --user=/tmp/dolphin-test2 \
  --exec=game2.iso &

wait

Performance Considerations

Faster-than-Realtime Execution

Remove framelimit for maximum speed:

dolphin-emu \
  --batch \
  --exec=game.iso \
  --config=Core.Framelimit=0 \
  --video_backend=Null

Deterministic Execution

Use interpreter core for reproducible results:

dolphin-emu \
  --batch \
  --exec=game.iso \
  --config=Core.CPUCore=0 \
  --config=Core.SyncGPU=True

Limitations

• No user interaction possible
• Cannot respond to prompts or dialogs
• No save/load state hotkeys
• No GUI configuration changes

Troubleshooting

Batch mode exits immediately

Ensure you specified --exec or --nand-title:

# Wrong - missing execution target
dolphin-emu --batch

# Correct
dolphin-emu --batch --exec=game.iso

Display server errors

On headless Linux systems, use xvfb-run or the Null backend:

# Option 1: Virtual framebuffer
xvfb-run dolphin-emu --batch --exec=game.iso

# Option 2: Null backend
dolphin-emu --batch --exec=game.iso --video_backend=Null

Games don’t stop automatically

Some games run indefinitely. Use timeout to limit execution:

timeout 300 dolphin-emu --batch --exec=game.iso

Complete Example

Automated game testing script:

#!/bin/bash

GAME_DIR="/games"
USER_DIR="/tmp/dolphin-test"
TIMEOUT=600

mkdir -p "$USER_DIR"

for game in "$GAME_DIR"/*.iso; do
  echo "Testing: $(basename "$game")"
  
  timeout $TIMEOUT dolphin-emu \
    --batch \
    --user="$USER_DIR" \
    --exec="$game" \
    --video_backend=Null \
    --config=Core.Framelimit=0 \
    --logger 2>&1 | tee "test-$(basename "$game").log"
  
  EXIT_CODE=$?
  
  if [ $EXIT_CODE -eq 0 ]; then
    echo "✓ Passed: $(basename "$game")"
  elif [ $EXIT_CODE -eq 124 ]; then
    echo "⚠ Timeout: $(basename "$game")"
  else
    echo "✗ Failed: $(basename "$game") (code: $EXIT_CODE)"
  fi
  
  echo "---"
done

rm -rf "$USER_DIR"

See Also

• Dolphin Options - All command-line flags
• Configuration - Using —config parameter