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 Raspberry Pi OS on an SD Card

You'll need to start with Raspberry Pi OS or Raspberry Pi OS Lite.

The last known for-sure tested-and-working version is Dec 11, 2023 (https://downloads.raspberrypi.org/raspios_lite_arm64/images/raspios_lite_arm64-2023-12-11/) from https://downloads.raspberrypi.org/raspios_lite_arm64/images/

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

Setup Virtual Environment

If you are installing on the Bookworm version of Raspberry Pi OS or later, you will need to install your python modules in a virtual environment. You can find more information in the Python Virtual Environment Usage on Raspberry Pi guide. To Install and activate the virtual environment, use the following commands:

sudo apt install python3.11-venv
python -m venv env --system-site-packages

To activate the virtual environment:

source env/bin/activate

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!

The latest installer script was rewritten in Python, so it can be installed with just a few commands. First, start by installing a few dependencies and downloading the repo:

cd ~
sudo apt-get update
sudo apt-get install -y git python3-pip
pip3 install --upgrade adafruit-python-shell click
git clone https://github.com/adafruit/Raspberry-Pi-Installer-Scripts.git
cd Raspberry-Pi-Installer-Scripts

Easy Single Command Install Options

The latest script allows you to specify all of your options within the command so you can sit back and watch the installation. We'll cover interactive installation below if you want to answer each prompt for a customized installation.

“Console Mode” Install Commands

If you just want a Linux text console to appear on the display, use one of the following commands:

For the PiTFT 2.4", 2.8", or 3.2" Resistive touchscreens, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=28r --rotation=90 --install-type=console

For the PiTFT 2.8" Capacitive touchscreen, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=28c --rotation=90 --install-type=console

For the PiTFT 2.2" Display, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=22 --rotation=90 --install-type=console

For the PiTFT 3.5" Resistive touchscreen, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=35r --rotation=90 --install-type=console

For the Mini PiTFT 1.3", BrainCraft HAT, 1.3" Color TFT Bonnet, or 1.5" Display, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x240 --rotation=0 --install-type=console

For the Mini PiTFT 1.14" Display, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x135 --rotation=270 --install-type=console

Mirrored Install Commands

If you want to mirror the HDMI output to the display, known as “FrameBuffer Copy” or FBCP for short, use one of the following commands:

For the PiTFT 2.4", 2.8", or 3.2" Resistive touchscreens, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=28r --rotation=90 --install-type=mirror

For the PiTFT 2.8" Capacitive touchscreen, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=28c --rotation=90 --install-type=mirror

For the PiTFT 2.2" Display, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=22 --rotation=90 --install-type=mirror

For the PiTFT 3.5" Resistive touchscreen, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=35r --rotation=90 --install-type=mirror

For the Mini PiTFT 1.3", BrainCraft HAT, 1.3" Color TFT Bonnet, or 1.5" Display, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x240 --rotation=0 --install-type=mirror

For the Mini PiTFT 1.14" Display, use the following command:

sudo -E env PATH=$PATH python3 adafruit-pitft.py --display=st7789_240x135 --rotation=270 --install-type=mirror

Rebooting

When it asks you to reboot, then choose yes because the setting won't take full effect until you do so.

Interactive Installation

For an interactive install, you can just run the script without any options:

sudo -E env PATH=$PATH python3 adafruit-pitft.py

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

Display Selection

Start by selecting the board that best corresponds with your PiTFT. There's lots of options and we will likely be adding more in the future.

Rotation

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 Raspberry Pi OS '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 Raspberry Pi OS with Desktop)

This option is easier to understand. This works more like a monitor, though slightly different depending on which desktop environment you are running.

As of Bookworm with the Wayland Graphical Environment, this operates a little different than it previously did. It works more in the way that multiple monitors do on desktop systems. The display is set up as its own monitor and will extend the desktop in addition to the HDMI.

With X11, this worked more as a mirror: 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?(or in the case of Wayland it will ask Would you like the to use the PiTFT as a desktop 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

Creating Your Own Automated Command

Under the Easy Single Command Install Options section, there are a bunch of different installation flags that you can choose between. If you want to create your own command, you can find the latest options by typing:

sudo python3 adafruit-pitft.py --help

The main options to pay attention to are the --display, --rotation, and --install-type arguments.

For the display, you can either choose the number you type for the options or the display type, which has the options listed under help. For instance, to us the 2.8" Resisitive display you could use

--display=1 or --display=28r

For the rotation, you can either choose the number you type for the options or the angle, which has the options also listed under help. To use 90 degrees, you could use

--rotation=1 or --rotation=90

For install type, You can either choose mirror, console or uninstall. To mirror, you would simply supply

--install-type=mirror

Automated Reboot Option

To go with a fully automated installation, you can provide a --reboot flag. To always reboot, use:

--reboot=yes

This is useful if you want to use the display right after running the script. To never reboot immediately, use

--reboot=no

This is useful if you want it as part of a larger script that installs many things.

Custom User Directory

By default, it is installed under the current user directory, but you can provide the -u or --user flag along with the folder that you want to install to.

Uninstalling The Driver

To uninstall, you would either run the script interactively and choose Uninstall or you can provide the uninstall flag:

--install-type=uninstall

Unsupported Full Images

Historically, we provided full 'images' of Raspbian, which is now called Raspberry Pi OS. 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 Sep 17, 2014. It was last updated on Mar 08, 2024.

This page (Easy Install) was last updated on Mar 08, 2024.

Text editor powered by tinymce.