Skip to content

Batocera CRT Script Installation Guide ‐ Wired Or Wireless Connection

Jump to bottom
Rion edited this page May 31, 2026 · 13 revisions

Caution

Unsupported Scan Rates & CRT Hardware Safety

During BIOS boot-up or when using unsupported video signals (e.g., out-of-range horizontal scan rates), CRT can experience hard stress on its deflection circuitry. In some older or lower-quality CRT displays, this may result in:

  • Overheated or saturated flyback transformer, horizontal deflection coil, or driver transistor
  • Potential component burnout (deflection ICs, coils, capacitors)

To minimize risk:

  • Keep the CRT powered off or switched to another input during BIOS/boot sequences
  • Avoid feeding non-CRT-safe signals until Batocera has properly initialized safe modelines via Switchres

What's New in v43 (vs v42)

Feature v42 v43
X11 exclusive Yes Yes
Zen3 Wayland/X11 dual-boot No Yes
HD/CRT Mode Switcher app No Yes (X11 Exclusive and Dual-Boot)
Port selection at install Choose any port (including disconnected) Same
Port changes after install Rerun script Same
Post-install VIDEO OUTPUT/MODE Manual Automatic (verify only)
240p boot/ES resolution Available Disabled (no official theme support)

Before You Install

Hardware compatibility

Confirm your GPU/APU and adapters are supported before flashing or running the installer:

PC CRT (31 kHz VGA/SVGA)? Use the dedicated wiki guide instead of the 15 kHz workflow:
PC CRT's & Setup Instructions

Handheld Devices

Pre-installation checklist

  • Batocera v43 image downloaded from batocera.org/download
    • For X11 Exclusive: Desktop PC, Laptop, NUC and Intel-based Apple Computers (download)
    • For Dual Boot Zen3 Wayland:
      • Steam Deck (download)
      • Optional: Desktop PC, Laptop, NUC and Intel-based Apple Computers (download & md5) These can also be downloaded from within the Batocera-CRT-Script if you care not to manually install both those files
  • USB drive or SSD flashed with that image
  • CRT display with correct cables/adapters (VGA, DVI-I, or DP with a proper DAC)
  • Batocera on your network; SSH client ready (phone or PC is fine)
  • GPU/APU that supports analog CRT output

Port capabilities (quick reference)

  • Analog-capable outputs for CRT: VGA, DVI-I
  • DisplayPort → requires a proper DP-to-VGA DAC; recommended on supported AMD dGPUs/APUs and NVIDIA nouveau
  • HDMI / DVI-D are digital-only (cannot natively output 15 kHz analog). Fine as a temporary install/SSH screen, not for the final CRT signal
  • NVIDIA proprietary driver: custom modes are more restricted; results vary by driver

Tip

If the CRT has no picture after install: confirm you selected the correct port in the script, rerun the script if you moved cables, and try an EDID/dummy plug on VGA, DVI-I, or DP (optional).

Recommended: install via SSH

SSH is the fastest way to run the installer. You do not need a second PC; a phone or laptop with an SSH client is enough.

📎 Batocera SSH Guide

iOS: Blink Shell, Termius, a-Shell, WebSSH
Android: ConnectBot, JuiceSSH, Termius, Termux

Choose Your Installation Path

Pick one guide below. Each includes flash steps, the curl installer (two equivalent URLs), script prompts, and post-install verification.

Important

Do not use Zen3 Dual-Boot unless you know your device supports and you plan on switching between an HD(PC or Handheld device) & CRT monitors using the HD/CRT Mode Switcher app. Keep in mind the HD/CRT Mode Switcher app also works in X11 Exclusive.

  • X11 Exclusive is correct if you only use a CRT, or HD + CRT on the standard x86_64 image.
  • Zen3 Dual-Boot is only for setups that require Zen3 Wayland on HD and switching to CRT with the Mode Switcher. Without that, Zen3 adds complexity for no benefit.
Path Batocera image Use when
X11 Exclusive Installation v43 x86_64 CRT-only PC, or HD + CRT on x86_64 with the HD/CRT Mode Switcher
Dual-Boot Installation (Zen3 Wayland + X11) v43 Zen3 You need Zen3 Wayland on the HD display (e.g. Steam Deck screen) and CRT via X11, with the HD/CRT Mode Switcher

After Installation (OPTIONAL)

Change CRT output port to a later

cd /userdata/system/Batocera-CRT-Script/Batocera_ALLINONE
chmod 755 Batocera-CRT-Script-v43.sh
./Batocera-CRT-Script-v43.sh

Select the new port when prompted, then reboot.

Troubleshooting

  • No CRT picture: wrong port selected, or digital-only output used for CRT
  • Overlay / install did not stick: reboot with Enter when the script asks; do not power off early
  • Logs: tail -100 /userdata/system/logs/BUILD_15KHz_Batocera.log
  • Help: Discord: ##crt-x86_64

Next Steps

Clone this wiki locally