Building ESP32 firmware with Espressif's IDF Docker image

If you're only occasionally building ESP32 firmware with Espressif's IoT Development Framework (ESP-IDF), your current build probably fails because the installation from last time is outdated. Then you have to reinstall the newest version of the framework and its dependencies, and you probably still encounter a dependency issue. If it finally works and you have successfully built your firmware, your excitement makes up for the frustrating experience, until the next time you want to build some other ESP32 firmware, and the process repeats.

But there's another way: use the IDF Docker image. It contains ESP-IDF, all the required Python packages, and all build tools such as CMake, make, ninja, and cross-compiler toolchains. In short: a ready-to-use IDF build system.

Building ESP32 firmware with CMake in the container is as easy as:

docker run --rm -v $PWD:/project -w /project espressif/idf build

This mounts the current directory on the host ($PWD) as the directory /project in the container and runs the command build on the code. After the build is finished, you can find your firmware in the current directory.


If you're building a project that needs a specific version of ESP-IDF, just use a tag such as espressif/idf:v4.2.1 instead of espressif/idf. You can find the available tags on Docker Hub.

The same works if the project is using make for its build:

docker run --rm -v $PWD:/project -w /project espressif/idf make defconfig all -j4

You can also use the container interactively.