CircuitPython eInk displayio Library Installation

To use displayio, you will need to install the appropriate library for your display. 

First make sure you are running the latest version of Adafruit CircuitPython for your board. You will need the latest version of CircuitPython.

To use the eInk displays with displayio, you will need to use the absolute latest version of CircuitPython and a board that can fit `displayio`. See the Support Matrix to determine if `displayio` is available on a given board:

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle.  Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.

You will need to copy the appropriate displayio driver from the bundle lib folder to a lib folder on your CIRCUITPY drive. The displayio driver contains the initialization codes specific to your display that are needed to for it to work. Since there is more than one driver, you will need to copy the correct file over. Here is a list of each of the displays and the correct driver for that display.

When downloading CircuitPython, for Grayscale support, you will need to choose Absolute Newest, choose your language, and then download the top-most link.


This display uses the Adafruit_CircuitPython_ILI0373 library. Copy the adafruit_il0373.mpy file from the bundle to the lib folder on your CIRCUITPY drive. You will want a recent version grayscale support was first added in version 1.3.1.


To show you how to use the eInk with displayio, we'll show you how to draw a bitmap onto it. First start by downloading display-ruler.bmp

Next copy display-ruler.bmp into the root directory of your CIRCUITPY drive.

In the examples folder for your displayio driver, there should be a test for your display which we have listed here:

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

"""Simple test script for 2.9" 296x128 grayscale display.

Supported products:
  * Adafruit 2.9" Grayscale

import time
import busio
import board
import displayio
import fourwire
import adafruit_il0373


# This pinout works on a Feather M4 and may need to be altered for other boards.
spi = busio.SPI(board.SCK, board.MOSI)  # Uses SCK and MOSI
epd_cs = board.D9
epd_dc = board.D10

display_bus = fourwire.FourWire(
    spi, command=epd_dc, chip_select=epd_cs, baudrate=1000000

display = adafruit_il0373.IL0373(

g = displayio.Group()

with open("/display-ruler.bmp", "rb") as f:
    pic = displayio.OnDiskBitmap(f)
    # CircuitPython 6 & 7 compatible
    t = displayio.TileGrid(
        pic, pixel_shader=getattr(pic, "pixel_shader", displayio.ColorConverter())
    # CircuitPython 7 compatible only
    # t = displayio.TileGrid(pic, pixel_shader=pic.pixel_shader)

    display.root_group = g




Save it to your CIRCUITPY drive as and it should automatically run. Your display will look something like this:

This guide was first published on Jul 18, 2018. It was last updated on May 17, 2024.

This page (CircuitPython Code) was last updated on May 17, 2024.

Text editor powered by tinymce.