It's easy to use display breakouts with Python and the Adafruit Blinka Displayio module.  This module allows you to easily write Python code to control the display.

We'll cover how to wire the display to your Raspberry Pi. First assemble your display.

Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported

Connect the display as shown below to your Raspberry Pi.

Note this is not a kernel driver that will let you have the console appear on the TFT. However, this is handy when you can't install an fbtft driver, and want to use the TFT purely from 'user Python' code!
You can only use this technique with Linux/computer devices that have hardware SPI support, and not all single board computers have an SPI device so check before continuing


  • Vin connects to the Raspberry Pi's 3V pin
  • GND connects to the Raspberry Pi's ground
  • CLK connects to SPI clock. On the Raspberry Pi, thats SLCK
  • MOSI connects to SPI MOSI. On the Raspberry Pi, thats also MOSI
  • CS connects to our SPI Chip Select pin. We'll be using CE0
  • RST connects to our Reset pin. We'll be using GPIO 24 but this can be changed later.
  • D/C connects to our SPI Chip Select pin. We'll be using GPIO 25, but this can be changed later as well.


You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling SPI on your platform and verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!

If you have previously installed the Kernel Driver with the PiTFT Easy Setup, you will need to remove it first in order to run this example.

Python Installation of ST7789 Library

Once that's done, from your command line run the following command:

  • sudo pip3 install adafruit-circuitpython-st7789 adafruit-circuitpython-display-text

If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!

If that complains about pip3 not being installed, then run this first to install it:

  • sudo apt-get install python3-pip

Pillow Library

We also need PIL, the Python Imaging Library, to allow graphics and using text with custom fonts. There are several system libraries that PIL relies on, so installing via a package manager is the easiest way to bring in everything:

sudo apt-get install python3-pil

NumPy Library

A recent improvement of the RGB_Display library makes use of NumPy for additional speed. This can be installed with the following command:

sudo apt-get install python3-numpy

Script Download and Modifications

Download the script using the wget command:

cd ~

Next, edit the script and make the following changes to use the correct pins:

spi = board.SPI()
tft_cs = board.CE0
tft_dc = board.D25

display_bus = displayio.FourWire(
    spi, command=tft_dc, chip_select=tft_cs, reset=board.D24

Now go ahead and run the script, the output should look like this:

Full Example

# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

This test will initialize the display using displayio and draw a solid green
background, a smaller purple rectangle, and some yellow text.
import board
import terminalio
import displayio

# Starting in CircuitPython 9.x fourwire will be a seperate internal library
# rather than a component of the displayio library
    from fourwire import FourWire
except ImportError:
    from displayio import FourWire
from adafruit_display_text import label
from adafruit_st7789 import ST7789

# Release any resources currently in use for the displays

spi = board.SPI()
tft_cs = board.D5
tft_dc = board.D6

display_bus = FourWire(spi, command=tft_dc, chip_select=tft_cs, reset=board.D9)

display = ST7789(display_bus, width=280, height=240, rowstart=20, rotation=90)

# Make the display context
splash = displayio.Group()
display.root_group = splash

color_bitmap = displayio.Bitmap(280, 240, 1)
color_palette = displayio.Palette(1)
color_palette[0] = 0x00FF00  # Bright Green

bg_sprite = displayio.TileGrid(color_bitmap, pixel_shader=color_palette, x=0, y=0)

# Draw a smaller inner rectangle
inner_bitmap = displayio.Bitmap(240, 200, 1)
inner_palette = displayio.Palette(1)
inner_palette[0] = 0xAA0088  # Purple
inner_sprite = displayio.TileGrid(inner_bitmap, pixel_shader=inner_palette, x=20, y=20)

# Draw a label
text_group = displayio.Group(scale=3, x=37, y=120)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=0xFFFF00)
text_group.append(text_area)  # Subgroup for text scaling

while True:

This guide was first published on Sep 08, 2021. It was last updated on Jun 22, 2024.

This page (Python Usage) was last updated on Jun 22, 2024.

Text editor powered by tinymce.