Public | Automated Build

Last pushed: 6 months ago
Short Description
ESP32, ESP8266, ESP8285 build environment of docker.
Full Description

ESP32, ESP8266 and ESP8285 build environment

It is a build environment of espressif's Wi-Fi(or bluetooth) Soc.


Chip support

  • ESP8266
  • ESP8285
  • ESP31B
  • ESP32 series

ESP8268 and ESP8689 not tested yet.


  • xtensa-lx106-elf toolchain
  • xtensa-esp108-elf toolchain
  • xtensa-esp32-elf toolchain
  • esptool-ck
  • python and pyserial


Install Docker

Follow the instructions at


Execute some command under this docker image

docker run --rm -ti -v `pwd`:$(somewhere) vowstar/esp8266 $(somecommand)

For example

docker run --rm -ti -v `pwd`:/build vowstar/esp8266 /bin/bash

This can mount host's `pwd` to container's /build path.

Programming Hardware

You could use Host's searial port to programming hardware, such as esp8266,esp32,nemu,device++, etc.

If you want flash espxx in docker's container, you can export host's serial ports to container, privileged permission needed.

The parameters is -v /dev/host:/dev/container

For example

docker run --name build --rm -ti --device /dev/ttyUSB0:/dev/ttyUSB0 -v `pwd`:/build vowstar/esp8266 /bin/bash

The --device flag can export a host device in container without privileged mode.

This can export host's /dev/ttyUSB0 in container's /dev/ttyUSB0.

And then, use container's esptool to program it.

For esp8266

esptool -cc esp8266 -cp /dev/ttyUSB0 -cd nodemcu -ca 0x00000 -cf 00000.bin -ca 0x40000 -cf 40000.bin

For esp32

esptool -cc esp32 -cp /dev/ttyUSB0 -cd nodemcu -ca 0x00000 -cf 00000.bin -ca 0x40000 -cf 40000.bin

Set build environment

For esp8266 freertos SDK

You can build it with ESP_RTOS_SDK for esp8266 by define SDK_BASE environment:

docker run -ti --name esp-builder -e SDK_BASE=/build/esp8266/ESP_RTOS_SDK/ --device /dev/ttyUSB0:/dev/ttyUSB0 -v ~/Projects/2016:/build vowstar/esp8266 /bin/bash

Firstly, you must put ESP_RTOS_SDK to ~/Projects/2016/esp8266/ESP_RTOS_SDK (aka container's /build/esp8266/ESP_RTOS_SDK).

Then you can make your project.

For esp32's esp-idf

You can build it with ESP-IDF for esp32 by define IDF_PATH environment:

docker run -ti --name esp-builder -e IDF_PATH=/build/esp32/esp-idf --device /dev/ttyUSB0:/dev/ttyUSB0 -v ~/Projects/2016:/build vowstar/esp8266 /bin/bash

Firstly, you must put ESP-IDF to ~/Projects/2016/esp32/ESP-IDF (aka container's /build/32/ESP-IDF).

Then you can make or make menuconfig, and use make flash to programming esp32.

For nodemcu project and normal esp8266 project

docker run -ti --name esp-builder --device /dev/ttyUSB0:/dev/ttyUSB0 -v ~/Projects/2016:/build vowstar/esp8266 /bin/bash

No special setting required, just build it.

Start and enter an old container

docker start esp-builder
docker attach esp-builder


Export all device to container

It may dangerous

docker run --name build --rm -ti --privileged -v /dev/ttyUSB0:/dev/ttyUSB0 -v `pwd`:/build vowstar/esp8266 /bin/bash

The --privileged flag can export all host device in container. May by you like --device flag to limit container access.

Build esp firmware On Windows/OS X

If you run docker under a VM, such as Oracle VM VirtualBox, the host's serial port and folder should share to VM
image first. You may need share host's USB device which used as serial adapter to VM image, a VirtualBox Extension Pack is needed for USB 2.0 and USB 3.0 devices.

For example, Mount D:\ drive on Windows using docker-machine in git bash

  • Share host's D:\ drive to docker linux images in VirtualBox, and name shared name d
  • Start docker image using docker machine docker-machine start default or other way
  • Mount vboxsf file-system using command below

docker-machine ssh default "sudo mkdir /d && sudo mount -t vboxsf -o uid=1000,gid=50 d /d"

And then, you can play

docker run --rm -ti -v /d/xxx:/build -w "/build" --env "SDK_BASE=/build/ESP_RTOS_SDK/" vowstar/esp8266 bash

/d/xxx is the host path, /build is the container PATH, use --env flag can pass some environment variable in container, such as SDK_PATH and BIN_PATH by espressif. Also you can pass something like --env APP=1 --env SPI_SIZE_MAP=2 --env BOOT=new for custom and special build.

Finally, make and use esptool to program it. Before programming, make sure the host usb to serial adapter is assigned to VirtualBox's linux image.

OSX is much easier, also need do same work on VirtualBox.

Build Dockerfile From Scratch

If you want build from scratch, please use Dockerfile-From-Scratch


This docker image uses esp-open-sdk. Thanks to the maintainer and creator Paul Sokolovsky who contributed it.

This Dockerfile is learn Marcel Stör's docker-nodemcu-build who contributed the NodeMCU online building service.

The toolchain comes from:

The program tool esptool-ck by Christian Klippel, which can programming both esp8266,esp8285 and esp32.

Docker Pull Command
Source Repository

Comments (2)
7 months ago

Hi @bclouser,

SDK 2.0 need extra rf_init code in any where your project:

#include "ets_sys.h"
#include "osapi.h"
#include "user_interface.h"
// ...
uint32 ICACHE_FLASH_ATTR __attribute__((weak))
    enum flash_size_map size_map = system_get_flash_size_map();
    uint32 rf_cal_sec = 0;

    switch (size_map) {
        case FLASH_SIZE_4M_MAP_256_256:
            rf_cal_sec = 128 - 5;

        case FLASH_SIZE_8M_MAP_512_512:
            rf_cal_sec = 256 - 5;

        case FLASH_SIZE_16M_MAP_512_512:
        case FLASH_SIZE_16M_MAP_1024_1024:
            rf_cal_sec = 512 - 5;

        case FLASH_SIZE_32M_MAP_512_512:
        case FLASH_SIZE_32M_MAP_1024_1024:
            rf_cal_sec = 1024 - 5;

            rf_cal_sec = 0;

    return rf_cal_sec;

void __attribute__((weak)) 

    // Control RF_CAL by esp_init_data_default.bin(0~127byte) 108 byte when wakeup
    // Will low current
    // system_phy_set_rfoption(0);

    // Process RF_CAL when wakeup.
    // Will high current

    // Set Wi-Fi Tx Power, Unit: 0.25dBm, Range: [0, 82]

I think attribute((weak)) is needed in user_rf_cal_sector_set.c of esp_open_sdk

8 months ago

Hello, I believe this has gone out of date now, since the release of sdk 2.0. I am seeing linking errors which i believe will be fixed by this commit in esp-open-sdk a few days ago. (

I should add that this docker image is great! Thank you for maintaining this!