Skip to main content
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