Esptool: update ESP8266 NodeMCU firmware on macOS is a python script that retrieves information about your ESP8266 module and flashes its firmware. In the previous article we used ESPFlasher to install a NodeMCU firmware on an ESP8266-based board (and even install a custom firmware through nodemcu-build), but ESPFlasher is only available for Windows (32 or 64 Bits) while esptool can run on all platforms that can run Python.

Prepare the ESP8266

If you are a beginner, we will use the Terminal to perform all the steps of this tutorial. You can find it in applications, in the Utilities folder, or by entering Terminal in Spotlight.

Provide an FTDI module (or cable) if your module is equipped with a programming interface via a COM port. requires Python 2.7 which is normally the default on Mac OS X. To find out if python is already present on your machine, simply type the python command in the Terminal. If everything is properly installed you should have a message like this


If this is not the case install python 2.7 by visiting here. Do not forget to leave python by entering exit (), quit () or Ctrl + D before continuing.

Let’s now go to the Document directory (or the directory of your choice, it is equal) like this

We will recover esptool by cloning it from github with command.

Go to the esptool directory

Now we will execute the script which allows to add the necessary dependencies (in particular pySerial). You will need to enter your password to allow the command to run.

Update firmware ESP8266 NodeMCU with on macOS

Now that esptool is ready, download the latest firmware NodeMCU ESP8266 by visiting github. Download the version that corresponds to your project. By default, take the integer version. To write this article, I used the binary nodemcu_integer_0.9.6-dev_20150704.bin.

Connect your ESP8266 NodeMCU card using an FTDI module (or a USB cable depending on the card you have).

To identify the serial port on which your card is located, you can use the Arduino IDE or enter the following command

The command returns the list of devices connected to your Mac. In my case it is connected to /dev/tty.usbserial-A1048DR2

All that remains is to prepare the command to flash the firmware. It is thus composed:

In the present case

Depending on your ESP8266 module, you may need to bootload this mode. Small reminder how to do for those who discover

  • Press and hold the GPIO0 button. The LED lights up at full power
  • Press the Reset button
  • Release Reset
  • Release the GPIO button. The led illuminates by half. The ESP8266 is in “bootload mode”

Now run the update command. If everything is correct, esptool starts by erasing the flash memory and then downloads the firmware. You can track the progress of the update from the terminal. The blue LED on the antenna will blink throughout the operation.

esptool flash firmware macos esp8266 update

Now open your Arduino IDE and open the Serial Monitor. Press the Reset button on the card. You should get a message indicating the firmware version and an error message

For further

If you need a custom firmware, for example a module only available on the development version, save space … you can read this previous article that shows how to get a custom firmware through frightanic nodemcu_build.

Firmware flashing is an energy consuming operation (with peaks between 200 and 300mA). Even if everything seems to have gone smoothly (the blue LED blinks during the operation, esptool does not indicate any error), it may happen that the firmware is incorrectly installed. Do not panic, simply add a complementary power supply, for example a LiPo battery 3.7 Volts by connecting it to the pin V+ and GND of your module then start again.

Subscribe to the weekly newsletter

No spam and no other use will be made of your email. You can unsubscribe anytime.


DIY Projects