lv_esp_idf is a reference project for running LVGL on an ESP32

A project layout, not a driver library

lv_esp_idf is described as LVGL ported to ESP32 including various display and touchpad drivers, and the README explains what it actually is.

It presents a common way of building LVGL applications on top of the ESP-IDF structure, and the stated intent is to serve as a reference for users that just wanted to dive in the application code while they abstract the project setup complexities.

That is a smaller claim than the repository description makes it sound, and it is the accurate one. This is not a set of display drivers you drop into your own project. It is a complete ESP-IDF application, with the CMake project file, the partition table, the sdkconfig defaults and the manifests for the boards it knows about, into which you drop your own code.

The division of labour inside the application is also described. The main application sets up the LVGL, plus the display and touch driver if any, and then it executes one of the selected LVGL demos such as the benchmarking or the music demo.

So the shape of the project is: hardware and drivers configured, LVGL initialised, and then a demo on screen. Replacing the demo with your own interface is the intended use, and everything above that line is the part you did not have to work out.

The implementation language is C, the default branch is master, and the last push to the repository was on 2026-09-16.

Two ways in, and one of them removes a step you would otherwise do

There are two ways of using the repository, through the LVGL Project Creator or by configuring it as a regular ESP-IDF project. The documentation covers the command line method, and it notes that the project can also be set up using the Espressif IDE.

The Project Creator route is: obtain the LVGL Project Creator, launch it, create an ESP IDF project, and follow the remaining steps, which includes setting up ESP-IDF.

The command line route is longer, and the first step is the same as for any ESP-IDF project. You need ESP-IDF itself.

$ . /path/to/esp-idf/export.sh
$ cd /path/to/this/repo

Then there is a step that is easy to miss, and the README calls it out explicitly. Before doing anything, remove the idf_component.yml file on the main folder, and the note says this step is valid only when not using the LVGL Project creator.

That file is the component manifest the Project Creator generates, and the two setup paths produce a different project layout. The command line path expects a plain ESP-IDF project, so leaving the manifest in place makes the two setups conflict.

The next step depends on your hardware. If you are going to build using one standard board from Espressif, you add its BSP package.

$ idf.py add-dependency esp32_p4_function_ev_board

Then you update the components, and using idf.py set-target is one option.

$ idf.py set-target esp32s3

The board support package and the target are separate choices, and it is worth being deliberate about the second one, because the target is what the build compiles for.

Build, flash, monitor

Once the project is set up with either the Project Creator or the Espressif tools, the build and flash sequence is the standard ESP-IDF one.

$ idf.py build
$ idf.py flash
$ idf.py monitor

The port can be given when it is not detected.

$ idf.py -p <COM or TTY port> flash

And the whole sequence can be concatenated into a single command.

idf.py -p <COM or TTY port> build flash monitor

The last form is the one that becomes muscle memory, and on a board that enumerates differently after a reboot it saves a lot of friction, since the port is stated once rather than every time.

The environment has to be set first in every case, with the export script, and the target has to be set before the first build if it has not been already.

One thing to be aware of is that the demo you see is not the point of the project. The application runs one of the LVGL demos, the benchmarking or the music demo, and those exist so that you can confirm the display, the touch and the rendering are all working before you write your own interface. The first hour with this project should end with a working demo and a working touch input, and only then with your own screens.

The manifests tell you which boards work out of the box

The Supported Boards section is short, and it points at a directory rather than at a list.

As any ESP-IDF project, this one can support a variety of ESP32 family boards, and the user can check the out-of-the-box supported boards by referring to the manifests folder.

So the manifests/ directory is the compatibility matrix. Each board that the project has been set up for has a manifest there, and a board without one is a board you are configuring yourself, which is where the idf.py add-dependency step comes in.

That is the practical meaning of the out-of-the-box qualifier. The project supports the ESP32 families in the sense that it can be built for them, and the manifests are the subset that has been prepared rather than assembled.

The board_images/ directory at the top level is the other clue about how the project is organised, since a repository that keeps images per board is one that expects people to be looking at the hardware while they read it.

For more detail the readme points to the Espressif section of the LVGL documentation, which has a dedicated section for the Espressif chips integration, and the readme says to visit it for more information about the integration details or tips and tricks about LVGL under Espressif chips. The point where this repository stops and the upstream documentation starts is the point where you need the specific hardware behaviour, the display driver setup and the LVGL configuration for your chip.

What the repository holds, and what the build defaults are

The top level listing is short enough to read in one line, and every entry has a purpose.

There is CMakeLists.txt, which is the ESP-IDF build definition, a main/ directory holding the application, the manifests/ directory with the board manifests, board_images/ with the per board images, partitions.csv for the flash layout, and two sdkconfig files, sdkconfig.defaults and sdkconfig.defaults.esp32s31.

The two sdkconfig files are the most informative pair, and the naming tells you the story. sdkconfig.defaults holds the settings applied to every target, and the.esp32s31 suffix is a target specific override for that chip. The two file names differ by a target suffix, which suggests the pattern for adding another target specific file.

partitions.csv is the other file with real consequences. The flash layout of a device is fixed at partition time, and getting it wrong is not something you discover at runtime, so the file is a starting point you should check against what your application needs, particularly if you plan to put an OTA update partition in there.

The.gitignore is the last entry, and it is worth knowing what is ignored, because ESP-IDF projects accumulate a lot of generated state. The generated directories are not part of the source, which is why the repository can stay small while the build produces a lot.

Checkpoint releases, and a repository without a licence identifier

The maintenance picture needs to be read carefully, and it is the main caveat in this project.

The repository is not archived, and the last push was on 2026-09-16, so somebody is still working on it. The release list, however, has only two entries, and both are old. v2.0, a checkpoint release, was published on 2020-12-16, and v1.0, also a checkpoint release, on 2020-09-03.

The word checkpoint is doing the work here. These are not numbered maintenance releases of a library with a compatibility promise, they are markers for a demonstration project. There is no version line that has been maintained for six years, because there is no version line.

The other thing to note is the licence. The repository records no standard licence identifier, and there is no LICENSE file in the top level listing. For a project whose main value is the code layout, the CMake project and the configuration defaults, the absence of a licence is a genuine gap. Without one, the default copyright rules apply, which means nobody else may copy and redistribute the configuration files as they stand.

The honest summary is that this is a well organised reference that has not been refreshed in the way a production project would need, and the upstream LVGL documentation, which the readme points to, is where the current guidance lives.

Editorial conclusion

Adopt lv_esp_idf as the starting point for an LVGL interface on an ESP32 when you want the project structure, the display and touch driver wiring and the board manifests laid out for you rather than assembled from scratch. Do not adopt it as a long lived dependency, because the checkpoint releases in the repository are from 2020 and the project is a demonstration rather than a maintained library. Verify first which of the boards in the manifests directory your hardware matches, that the target you set with idf.py set-target is the one your board uses, and that you read the LVGL Espressif integration documentation, which the project points to for the details it does not cover.

Frequently asked questions

Official sources

1. Issues
2. lvgl/lv_esp_idf on GitHub
3. README
4. Releases