Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Marcussacapuces91/doc-TFT_eSPI/llms.txt

Use this file to discover all available pages before exploring further.

TFT_eSPI can be installed in two ways depending on your development environment. Arduino IDE users can install it directly from the built-in Library Manager with a single search-and-click workflow. PlatformIO users declare the dependency in platformio.ini and the toolchain fetches it automatically during build. Both methods get you the same library, but PlatformIO offers the additional advantage of keeping per-project configuration files separate from your global library folder.
Updating TFT_eSPI through either the Arduino Library Manager or PlatformIO will overwrite your local changes to User_Setup.h and any custom setup files in the library folder. Back up your configuration before upgrading, or use the PlatformIO per-project build_flags approach described in the Configuration guide to keep settings version-safe.

​
Arduino IDE

1

Open the Library Manager

In the Arduino IDE menu, navigate to Sketch → Include Library → Manage Libraries… (or press Ctrl+Shift+I on Windows/Linux, ⌘+Shift+I on macOS) to open the Library Manager panel.
2

Search for TFT_eSPI

Type TFT_eSPI in the search box. The library by Bodmer will appear at the top of the results. Confirm the author name matches to avoid installing an unrelated package.
3

Install the library

Click the Install button next to the latest version. The IDE will download and place the library in your Arduino libraries folder:
  • Windows: C:\Users\<username>\Documents\Arduino\libraries\TFT_eSPI\
  • macOS: ~/Documents/Arduino/libraries/TFT_eSPI/
  • Linux: ~/Arduino/libraries/TFT_eSPI/
4

Configure for your hardware

Before uploading any sketch, open User_Setup.h inside the installed library folder and configure it for your specific display and pin wiring. See the Configuration guide for full details.

​
PlatformIO

1

Open or create platformio.ini

Every PlatformIO project contains a platformio.ini file at the project root. Open it in your editor — if starting a new project, PlatformIO IDE will have generated one for you.
2

Add TFT_eSPI to lib_deps

Under your [env:...] section, add TFT_eSPI to the lib_deps key. PlatformIO will resolve and download the library from its registry on the next build.
3

Add display configuration via build_flags

PlatformIO lets you define TFT_eSPI settings on a per-project basis using build_flags instead of editing the shared User_Setup.h. This keeps your configuration inside your project repository and safe from library upgrades.
4

Build the project

Run Build (the checkmark button) or execute pio run in the terminal. PlatformIO fetches TFT_eSPI and compiles your project with the settings defined in platformio.ini.
[env:esp32dev]
platform  = espressif32
board     = esp32dev
framework = arduino

lib_deps =
    bodmer/TFT_eSPI

; Per-project display configuration — overrides User_Setup.h
build_flags =
    -D USER_SETUP_LOADED=1
    -D ILI9341_DRIVER=1
    -D TFT_MOSI=23
    -D TFT_SCLK=18
    -D TFT_CS=5
    -D TFT_DC=2
    -D TFT_RST=4
    -D TFT_WIDTH=240
    -D TFT_HEIGHT=320
    -D SPI_FREQUENCY=27000000
When using the build_flags approach in PlatformIO you must set -D USER_SETUP_LOADED=1 first. This preprocessor flag tells TFT_eSPI to skip loading User_Setup.h entirely and use only the definitions supplied by your build flags. Without it the library will still read User_Setup.h and your flags may conflict.

Build docs developers (and LLMs) love

Get started for freeTalk to us