Display Troubleshooting

It may help to activate your Nvidia drivers/Intel i965 drivers first if using those GPUs.

Older 8-bit and 16bit systems, or arcade systems from the 80s and 90s were using 4:3 CRT screens. Modern displays are now 16:9 or wider, and can go up to 4K, i.e. 2160 pixels high (compared to 480 or 546 at the time!).

Having so many pixels to render on the screen is impactful on the system performance. When you have a 4K screen or an ultra-wide screen, Batocera will limit the resolution by default to HD 1920×1080. It's more than enough to render emulators, even the most recent ones. However, when you have an ultra-wide monitor, the display may be stretched.

For 4K monitors, because the resolution is by default resized to 1920×1080, you might see a screen that looks like this one (actually it's what 1:1 pixel scaled 1920×1080 is, centered in a 3840×2160 screen):

First, check your TV's scaling settings to ensure that it is currently set to “Stretch”, “Full screen”, “Expand”, “Fill” or some terminology similar to that.

If you've checked for that and the image is still tiny, the best solution is to manually set the resolution to “1920×1080” (or “MAXIMUM 1920×1080”) in MAIN MENUGAMES SETTINGSVIDEO MODE (you can instead do that on a system-by-system basis in the PER SYSTEM ADVANCED CONFIGURATION screen).

ES's video mode screen shows a list of available resolutions/their alternate modes.

Another use case is when you have a 1280×720 TV, for example, and you want to use bezels that are designed for 1920×1080. Batocera can automatically resize the bezels, but sometimes you need to force the VIDEO MODE to take your 1280×720 resolution.

If you absolutely want to use the 4K resolution for whatever reason (shaders looking better, you have a non-standard wide format on your TV/monitor…), set the VIDEO MODE to “3840×2160” (turn on the STRETCH BEZEL option to force the use of bezels designed for 1920×1080 on your 4K resolution, stretching bezels is not available in Batocera 5.27 and lower). As above, this is something you can do on a system-by-system basis instead.

Setting the resolution to force 4K has an impact on the emulation performance.

This shouldn't be necessary for most TVs that provide a proper EDID packet, but is here for those specific situations where they don't.

There are some SBC + TV combinations where EmulationStation feels sluggish (default theme seems to be lagging behind, with a refresh rate like 10 FPS). It's really depending on your own configuration, but we have reproduced this with a Raspberry Pi 4 and a couple 4K TV models. By default, ES should negotiate with your TV to fix its resolution to 1080p, but sometimes your TV brand doesn't accept it and stays at 4K/2160p resolution. You can force a particular resolution by editing it into /boot/batocera-boot.conf.

In Batocera v31 and higher, the max-1920×1080 resolution is now an option available to select within the standard es.resolution key. To force a maximum resolution of 1920×1080:


You can also force a maximum resolution of 640×480 instead for really slow devices:


For earlier versions of Batocera (v29 and v30), this option cannot be selected in es.resolution (it will be ignored). Instead, you must use a different key in batocera-boot.conf:


After this, Batocera will take the most suitable refresh rate for the maximum resolution specified and use that.

You can get the list of all supported resolution by running the following commands via SSH:

export DISPLAY=:0.0
batocera-resolution listModes

For example:

[root@BATOCERA /userdata/system]# export DISPLAY=:0.0
[root@BATOCERA /userdata/system]# batocera-resolution listModes
max-1920x1080:maximum 1920x1080
max-640x480:maximum 640x480

Any resolution listed here can be used in the es.resolution line. For example, es.resolution=1280×720.

This section is for PC x86 and x86_64, not for SBCs like Raspberry Pi or Odroid, and mostly outdated as most cases should be handled with the section above.

This tutorial is useful if you have display issues, for instance if you need to rotate your screen, or use a lower refresh rate.

On Batocera v30 and lower, Batocera would simply select the highest available resolution + refresh rate your display reports as supported. Obviously, when running Batocera on weak SBCs like the Raspberry Pi connected to a 4K UHD TV, this would cause visual stutter as the SBC isn't powerful enough to output a 4K resolution at 60 FPS. You would need to force a smaller resolution (like 1920×1080) to get better performance in this scenario.

Fortunately, from Batocera v31 and higher, Batocera will default to using the 1920×1080 resolution as its maximum (and if you have one of those rare displays that support 120Hz or higher, it will default to that too for silky-smooth menu navigation! But only in EmulationStation, in-game will still be 60Hz by default). You can switch to using a genuine 4K resolution by setting your VIDEO MODE in GAME SETTINGS to 3840×2160, though even this won't have much a visual difference for most retro-games.

First of all, you need to connect on your Batocera through SSH. Then run the following commands:

export DISPLAY=:0.0

This will output your display's reported “supported resolutions” (the currently used refresh rate will be marked with an asterisk (*) on the line of the current resolution being used). This is an example with an old 4/3 screen, but this is the same principle for other screens:

Screen 0: minimum 8 x 8, current 1366 x 768, maximum 32767 x 32767
LVDS1 connected primary 1366x768+0+0 (normal left inverted right x axis y axis) 290mm x 160mm
1366x768 60.03*+ 40.03
1024x768 60.00
1024x576 60.00
960x540 60.00
800x600 60.32 56.25
864x486 60.00
640x480 59.94 

If you have an error message telling you “can't open display :0.0”, you need to physically log onto your Batocera system with the display on. On a PC from EmulationStation, press [F1] and then launch a terminal from there (xterm from the Applications shortcut in the left sidebar).

If you'd like to edit the display output, you can copy the current display configuration file at /usr/bin/emulationstation/ to your userdata partition at /userdata/system/custom-es-config and use that instead. On PC, you can use the file manager ([F1] on the system list) for this.

You can do so from SSH instead by running the following:

cp /usr/bin/emulationstation-standalone /userdata/system/custom-es-config

In Batocera v31 and lower, the original file was at /etc/X11/xinit/xinitrc and the userdata copy was at /userdata/system/.xinitrc instead, so the command would instead be:

cp /etc/X11/xinit/xinitrc /userdata/system/.xinitrc

You can also edit the file from SSH by running the following:

nano /usr/bin/emulationstation-standalone

For Batocera v31 and lower, this would be nano /userdata/system/.xinitrc instead.

Scroll down (using the arrow keys) to the following section:

# to customize your display, you can create the file /userdata/system/custom-es-config
# including this kind of commands
# rotate the screen
# xrandr -o left
# xrandr -o right
# xrandr -o inverted

# change the resolution
# xrandr -s 640x480

# change the resolution and the Hz
# xrandr -s 640x480 -r 60


Just uncomment (remove the hash character from the start of the line) the corresponding line with the option you want (changing it if something else is desired). For example, to just force a resolution of 640×480:

# change the resolution
xrandr -s 640x480

# change the resolution and the Hz
# xrandr -s 640x480 -r 60

To instead change the resolution to 1280×720 at 120Hz:

# change the resolution
# xrandr -s 640x480

# change the resolution and the Hz
xrandr -s 1280x720 -r 120


Save the file with [Ctrl] + [S] and quit with [Ctrl] + [Q].

EmulationStation by default runs in full-screen, and may use the old full-screen resolution even through restarts, cutting off a part of its display. For testing purposes, you can temporarily use windowed mode for the current session with:

exec emulationstation --windowed

Then restart EmulationStation with the following commands to test your new resolution:

/etc/init.d/S31emulationstation stop
/etc/init.d/S31emulationstation start

If you were to reboot Batocera at this point, you'll find that all the settings you just created have been lost. In order to make these settings permanent, you must save the overlay with the following command before rebooting:


xrandr can do screen rotation; very useful for old vertical screen arcade machines!

Hope this was easy for all.

  • display_issues.txt
  • Last modified: 2 weeks ago
  • by atari