Public | Automated Build

Last pushed: 2 months ago
Short Description
Edit NodeMCU for ESP8266 on your favorite platform. Docker will build it on Linux for you.
Full Description

Docker NodeMCU build

Clone and edit the NodeMCU firmware locally on your platform. This image will take it from there and turn your code into a binary which you then can flash to the ESP8266.

Target audience

I see 3 types of NodeMCU developers:

  • NodeMCU "application developers"

    They just need a ready-made firmware. I created a cloud build service with a nice UI and configuration options for them.

  • Occasional NodeMCU firmware hackers

    They don't need full control over the complete tool chain and don't want to setup a Linux VM with the build environment. This image is exactly for them!

  • NodeMCU firmware developers

    They commit or contribute to the project on GitHub and need their own full fledged build environment with the complete tool chain. They still might find this Docker image useful.


Install Docker

Follow the instructions at

Clone the NodeMCU firmware repository

Docker runs on a VirtualBox VM which by default only shares the user directory from the underlying guest OS. On Windows that is c:/Users/<user> and on Mac it's /Users/<user>. Hence, you need to clone the NodeMCU firmware repository to your user directory. If you want to place it outside the user directory you need to adjust the VirtualBox VM sharing settings accordingly.

git clone

Run this image with Docker

Start Docker and change to the NodeMCU firmware directory (in the Docker console). Then run:

docker run --rm -ti -v `pwd`:/opt/nodemcu-firmware marcelstoer/nodemcu-build

Depending on the performance of your system it takes 1-3min until the compilation finishes. The first time you run this it takes longer because Docker needs to download the image and create a container.

:bangbang: If you have previously pulled this Docker image (e.g. with the command above) you should update the image from time to time to pull in the latest bug fixes:

docker pull marcelstoer/nodemcu-build

Note for Windows users

(Docker on) Windows handles paths slightly differently. You need to specify the full path to the NodeMCU firmware directory in the command and you need to add an extra forward slash (/) to the Windows path. The command thus becomes (c equals C drive i.e. c:):

docker run --rm -it -v //c/Users/<user>/<nodemcu-firmware>:/opt/nodemcu-firmware marcelstoer/nodemcu-build

If the Windows path contains spaces it would have to be wrapped in quotes as usual on Windows.

docker run --rm -it -v "//c/Users/monster tune/<nodemcu-firmware>":/opt/nodemcu-firmware marcelstoer/nodemcu-build


The two firmware files (integer and float) are created in the bin sub folder of your NodeMCU root directory. You will also find a mapfile in the bin folder with the same name as the firmware file but with a .map ending.


You can pass the following optional parameters to the Docker build like so docker run -e "<parameter>=value" -e ....

  • IMAGE_NAME The default firmware file names are nodemcu_float|integer_<branch>_<timestamp>.bin. If you define an image name it replaces the <branch>_<timestamp> suffix and the full image names become nodemcu_float|integer_<image_name>.bin.
  • INTEGER_ONLY Set this to 1 if you don't need NodeMCU with floating support, cuts the build time in half.
  • FLOAT_ONLY Set this to 1 if you only need NodeMCU with floating support, cuts the build time in half.

Flashing the built binary

There are several tools to flash the firmware to the ESP8266. If you were to use esptool (like I do) you'd run: --port <USB-port-with-ESP8266> write_flash 0x00000 <NodeMCU-firmware-directory>/bin/nodemcu_[integer|float]_<Git-branch>.bin


Don't leave comments on Docker Hub that are intended to be support requests. First, Docker Hub doesn't notify me when you write them, second I can't properly reply and third even if I could often it doesn't make much sense to keep them around forever and a day. Instead ask a question on StackOverflow and assign the nodemcu and docker tags.

For bugs and improvement suggestions create an issue at


Thanks to Paul Sokolovsky who created and maintains esp-open-sdk.


Docker Pull Command

Comments (6)
2 months ago

Thank you very much for your work for me to create interesting offers a great help.
About ten days ago I can successfully compile the bin file, but now it seems a little bit of trouble.
Now I met a problem, this problem bothering me one day.The problem is this:$ docker run --rm -it -v "//C/Users/Administrator/nodemcu-firmware":/opt/nodemc
u-firmware marcelstoer/nodemcu-build
fatal: Not a git repository (or any parent up to mount point /opt/nodemcu-firmwa
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
cp: cannot stat 'tools/esp-open-sdk.tar.*': No such file or directory.
I hope you can see this message.
Thank you very much, from an old friend of China.

8 months ago

Handy post on with some info about this excellent container, like how to select which modules to build:

10 months ago

Very good tutorial ;)
I've followed it with W10 Familly x64. Of course with Docker Toolbox and enabling BIOS virtualization instead of Docker for Windows.
Thank you very much.

a year ago

I'm trying to use Docker (on Windows). I've cloned the repository (C:\Users\Mare\nodemcu-firmware). When I execute the following from that folder:
docker run --rm -it -v //c/Users/Mare/nodemcu-firmware:/opt/nodemcu-firmware marcelstoer/nodemcu-build
I get the following errors:
fatal: Not a git repository (or any parent up to mount point /opt/nodemcu-firmware)
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
cp: cannot stat 'tools/esp-open-sdk.tar.gz': No such file or directory

I'm able to call "git status" from the same shell, so I guess the availability of git is not a problem..

a year ago

thanks for the setup Marcel. Is there a way to install a portable version of Docker on a Mac? I don't have admin rights on the Mac machine here.

a year ago

Thank you for this very useful image. Good job!