My PiTFT used to work, now it doesn't!

If you messed with /boot/config.txt or /etc/rc.local you may have removed or disabled some of the elements required for the PiTFT to work. Try re-running the Easy Installer script!

I have a Pi 4 or Pi 400 and my HDMI output looks very weird

The Raspberry Pi 4 and the Raspberry Pi 400 have dual HDMI outputs. However, only one of those is a primary port. The is likely caused by connecting to HDMI1. Please try connecting the display to the other HDMI port and rebooting.

For the Pi 4, HDMI 0 is closer to the USB-C port. For the Pi 400, it's the port closer to the MicroSD Card slot.

I'm booting my Pi with the PiTFT and the HDMI output 'locks up' during boot!

It looks like the Pi is 'halting' or 'locking' up during boot but what is really happening is the console is switching from the HDMI output to the PiTFT console output.

Check your PiTFT connections, particularly make sure you seated the PiTFT on the Pi properly, nothing is in the way, and the TFT flex connector is seated properly.

My PiTFT works for a bit and then I get a black screen with a short line of white pixels in one corner

Sounds like you tried to configure your Pi to 'boot straight to X', that is, start up the graphics interface on boot. This doesn't work by default because the Pi operating system is not expecting a PiTFT so it boots to the HDMI output. See below for how to set up your Pi to boot to X on the PiTFT

To 'fix' this, you can either connect an HDMI monitor, then in a terminal window run sudo raspi-config and configure the Pi to boot to the command line not X! If you do not have an HDMI monitor, you can also try a console cable

I'm tring to run startx and I get FATAL: Module g2d_23 not found.
don't forget you have to remove the turbo file!
sudo mv /usr/share/X11/xorg.conf.d/99-fbturbo.conf ~
How come OMX-Player and Minecraft and other programs don't appear on the PiTFT display?

Some programs are graphics-optimized, particularly the video playback tools and some other programs like Minecraft. They write 'directly' to the HDMI output, and cannot write to the PiTFT so there is no way to directly make them work. However, you can have the output go to HDMI and then mirror the HDMI onto the PiTFT with fbcp. Using the Easy Installer, select Mirror HDMI

Why doesn't the tactile button on GPIO #21 work?
On some older PiTFTs we had one of the buttons labeled #21 - that's the original RasPi name for that pin. If you're using a V2 (chance is, you are!) that is now called #27.
All the PiTFT's we ship now have the button labeled #21 and #27
I want better performance and faster updates!

You can change the SPI frequency (overclock the display) by editing /boot/config.txt and changing the dtoverlay options line to:


Or whatever you like for speed, rotation, and frames-per-second. BUT, here's the thing, the Pi only supports a fixed number of SPI frequencies. So tweaking the number a little won't do anything. The kernel will round the number to the closest value. You will always get frequencies that are 250MHz divided by an even number. Here's the only SPI frequencies this kernel supports

  • 15,625,000 (a.k.a 16000000 = 16 MHz)
  • 17,857,142 (a.k.a. 18000000 = 18 MHz)
  • 20,833,333 (a.k.a 21000000 = 21 MHz)
  • 25,000,000 (= 25 MHz)
  • 31,250,000 (a.k.a 32000000 = 32MHz)
  • 41,666,666 (a.k.a 42000000 = 42MHz)
  • 62,500,000 (a.k.a 62000000 = 62MHz)

So if you put in 48000000 for the speed, you won't actually get 48MHz, you'll actually only get about 42MHz because it gets rounded down. We tested this display nicely with 32MHz and we suggest that. But you can put in 42MHz or even try 62MHz and it will update faster

You can tweak fps (frames per second) from 20 to 60 and frequency up to 62MHz for tradeoffs in performance and speed. Reboot after each edit to make sure the settings are loaded properly. There's a trade off that if you ask for higher FPS you're going to load the kernel more because it's trying to keep the display updated.

How can I take screenshots of the little screen?
How do I automatically boot to X windows on the PiTFT?

Make sure your Pi boots to the graphical PIXEL desktop on the HDMI output monitor, then using the Easy Installer, select Mirror HDMI

My screen isn't working/works erratically/looks funny

Check to make syre that the flat flex cable is fully seated in the connetor and the 'ears' are pushed in to secure it. See the picture for what it should look like:

On my first run of startx I get a window saying "GDBus Policy Kit1 Error: Failed Cannot determine user of subject"

This happens on the Raspberry Pi the first time you run startx, no matter what display. You can just re-start X and it wont appear again.

Can I get a right-click from the touch-screen?
I'm having difficulties with the STMPE resistive touch screen controller
My PiTFT's rotation/calibration isn't working in X11

X11 (the graphical system) has changed how it gets touchscreen input, so if you rotate the display and the calibration isn't being picked up:

Check /usr/share/X11/xorg.conf.d for a file called 10-evdev.conf 

If you don't see that file

  1. You need to sudo apt-get install xserver-xorg-input-evdev, and then...
  2. If you do have a 40-libinput.conf in that same directory, you must remove it even if/once evdev is installed, since it will override the 10-evdev.conf otherwise.

Thanks to cerebrate in the forums for the hint!

White Screen Issue

A small number of Adafruit PiTFT - Touchscreen Display for Raspberry Pi were manufactured in error in 2018. If you have a display from that era with a white screen issue, see this forum post for diagnosis and remedy.

This guide was first published on Nov 29, 2013. It was last updated on Apr 04, 2024.

This page (HELP! (FAQ)) was last updated on Mar 27, 2024.

Text editor powered by tinymce.