> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dolphin-emu/dolphin/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
dolphin-emu --batch --exec=/path/to/game.iso
```

## Common Use Cases

### Automated Testing

Run games automatically to completion:

```bash theme={null}
#!/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:

```bash theme={null}
dolphin-emu \
  --batch \
  --exec=game.iso \
  --movie=worldrecord.dtm
```

### Save State Loading

Start from a specific save state:

```bash theme={null}
dolphin-emu \
  --batch \
  --exec=game.iso \
  --save_state=checkpoint.sav
```

### Configuration Testing

Test different emulation settings:

```bash theme={null}
dolphin-emu \
  --batch \
  --exec=game.iso \
  --config=Core.CPUCore=1 \
  --config=Core.Overclock=2.0
```

### Continuous Integration

Run regression tests in CI/CD pipelines:

```yaml theme={null}
# .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`:

```bash theme={null}
dolphin-emu \
  --batch \
  --exec=game.iso \
  --config=Core.CPUCore=1 \
  --config=Core.SyncOnSkipIdle=False \
  --video_backend=Null
```

### Useful Batch Mode Configurations

```bash theme={null}
# 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:

```bash theme={null}
dolphin-emu \
  --batch \
  --exec=game.iso \
  --video_backend=Null
```

### Software Renderer (For Testing)

CPU-based rendering, deterministic:

```bash theme={null}
dolphin-emu \
  --batch \
  --exec=game.iso \
  --video_backend="Software Renderer"
```

### Hardware Backends (With Display Server)

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

```bash theme={null}
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:

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

## Logging

Enable logging to capture output:

```bash theme={null}
dolphin-emu \
  --batch \
  --logger \
  --exec=game.iso 2>&1 | tee dolphin.log
```

## User Directory

Use isolated user directories for parallel execution:

```bash theme={null}
# 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:

```bash theme={null}
dolphin-emu \
  --batch \
  --exec=game.iso \
  --config=Core.Framelimit=0 \
  --video_backend=Null
```

### Deterministic Execution

Use interpreter core for reproducible results:

```bash theme={null}
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`:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
timeout 300 dolphin-emu --batch --exec=game.iso
```

## Complete Example

Automated game testing script:

```bash theme={null}
#!/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](/cli/dolphin-options) - All command-line flags
* [Configuration](/cli/configuration) - Using --config parameter