Easy Install

The PiTFT requires some device tree support and a couple other things to make it a nice stand-alone display. If you just want to get going, check out the following for easy-install instructions!

The same installer is used for all PiTFTs, you will pick and configure the setup during installation!

Install Raspbian on an SD Card

You'll need to start with Raspbian or Raspbian Lite.

The last known for-sure tested-and-working version is March 13, 2018 (https://downloads.raspberrypi.org/raspbian/images/raspbian-2018-03-14/) from https://downloads.raspberrypi.org/raspbian/images/

Raspbian does often 'break' stuff when new versions come out so to be safe, if you are having problems try this version!

Installer script

This script will do all the work for you, and install both device tree overlay support as well as configure rotation and any HDMI mirroring. PiTFT no longer needs any custom kernels or modules, so you can continue to update/upgrade your Pi and it will work with the most recent releases.

Here's the commands to run. Make sure your Pi has network access, it needs to download the software!

Download: file
cd ~
wget https://raw.githubusercontent.com/adafruit/Raspberry-Pi-Installer-Scripts/master/adafruit-pitft.sh
chmod +x adafruit-pitft.sh
sudo ./adafruit-pitft.sh

PiTFT Selection

Once you run it you will be presented with menus for configuration.

For the 2.4", 2.8" and 3.2" PiTFT with resistive touchscreen overlay select #1

For the 2.2" PiTFT select #2

For the 2.8" Capacitive PiTFT select #3

For the 3.5" PiTFT select #4


Next you will be asked for the rotation you want, don't worry if you're not 100% sure which you want, you can always change this later by re-running the script

It will take a few minutes to install the software and download all the things...

Configuring what shows where

You have a few different ways to set up the PiTFT, we ask 2 questions to figure out what you want

PiTFT as Text Console (best for Raspbian 'Lite')

This is the simplest to set-up type of use. Its great if you have a simple text based or pygame/SDL based interface. If you want the PiTFT to act as a text console you can expect:

  • HDMI will be 'deactivated' - nothing appears on the HDMI output but a black screen
  • The login prompt appears on the Pi
  • The Pi is all text, not a GUI (no PIXEL desktop)
  • Keyboard and mouse are used only by the PiTFT interface
  • Framebuffer-capable software (such as fbi for displaying images, mplayer for videos, or pygame software, etc) appear on the PiTFT
  • OpenGL accelerated software will not appear on the PiTFT (it is unaccelerated framebuffer only)
  • But, non-OpenGL-accelerated graphics software is a bit faster than using HDMI mirroring (not tons faster but you're not running fbcp which will always make it faster)

If you want that say Yes to the question Would you like the console to appear on the PiTFT display

Then simply reboot. Once rebooted you will not see anything on HDMI, but the console will appear on the PiTFT. That's it!

PiTFT as HDMI Mirror (Best for Raspbian Full/PIXEL)

This option is the easiest to understand: whatever appears on the HDMI display will be 'mirrored' to the PiTFT. Note that HDMI is much higher resolution so it's not like it turns the PiTFT into a 1080p display. This is great for when you want to run OpenGL-optimized software, PIXEL desktop software, or really anything. The down-side is its a little slower than drawing directly to the framebuffer. You may not notice it but it's worth us mentioning!

  • HDMI will be 'activated' but at a lower resolution - you can change this later but it looks best at 320x240 (PiTFT 2.2", 2.4", 2.8" and 3.2") or 480x320 (PiTFT 3.5")
  • The login prompt or GUI appears on both HDMI and PiTFT at the same time
  • Keyboard and mouse are shared, since the display is mirrored
  • All graphics appear on both HDMI and PiTFT, thanks to fbcp

If you want that say Yes to the question Would you like the HDMI display to mirror to the PiTFT display?

PiTFT as Raw Framebuffer Device

For advanced users who are comfortable using framebuffer devices, it is possible to have the PiTFT and HDMI graphics be both active and display different data.

  • HDMI will be active and act like a normal Pi
  • The login prompt or GUI (PIXEL) appears on the HDMI
  • PiTFT appears black, nothing appears on it
  • Keyboard and mouse are used by the HDMI interface but can, in theory, be captured and used to change graphics on PiTFT through programming
  • Framebuffer-capable software (such as fbi for displaying images, mplayer for videos, or pygame software, etc) can appear on the PiTFT if you set it up to display to /dev/fb1
  • OpenGL accelerated software will never appear on the PiTFT (it is unaccelerated framebuffer only)

If you want that, say No to both of the configuration questions!

You can always change your mind after setting up one of the configurations, depending on your needs! Just re-run the script

Unsupported Full Images

Historically, we provided full 'images' of Raspbian. This worked OK until Raspbian started doing releases every few months. These are no longer supported, and won't even boot on Pi 3B+, so we recommend the script above.

There's the larger 'classic Jessie' image that will boot into X by default, and requires a 8G image, it has a lot more software installed. There's also the smaller 'Jessie Lite' that will boot into the command line, and can be burned onto a 2G card! Click below to download and install into a new SD card. Unzip and follow the classic SD card burning tutorials

PiTFT 2.2" Images

PiTFT 2.4"/2.8"/3.2" Resistive Images

PiTFT 2.8" Capacitive

PiTFT 3.5" Images

This guide was first published on Jul 21, 2014. It was last updated on Jul 21, 2014.
This page (Easy Install) was last updated on Aug 04, 2020.