Installing the ESP32 Board in Arduino IDE (Windows, Mac OS X, Linux)

There’s an add-on for the Arduino IDE that allows you to program the ESP32 using the Arduino IDE and its programming language. In this tutorial we’ll show you how to install the ESP32 board in Arduino IDE whether you’re using Windows, Mac OS X or Linux.

Watch the Video Tutorial

This tutorial is available in video format (watch below) and in written format (continue reading this page). 

If you have any problems during the installation procedure, take a look at the ESP32 Troubleshooting Guide.

If you like the ESP32, enroll in our course: Learn ESP32 with Arduino IDE.

Prerequisites: Arduino IDE Installed

Before starting this installation procedure, make sure you have the latest version of the Arduino IDE installed in your computer. If you don’t, uninstall it and install it again. Otherwise, it may not work.

Having the latest Arduino IDE software installed from arduino.cc/en/Main/Software, continue with this tutorial.

Do you need an ESP32 board? You can buy it here.

Installing ESP32 Add-on in Arduino IDE

To install the ESP32 board in your Arduino IDE, follow these next instructions:

  1. In your Arduino IDE, go to File> Preferences

    Installing ESP32 Add-on in Arduino IDE Windows, Mac OS X, Linux open preferences
  2. Enter https://dl.espressif.com/dl/package_esp32_index.json into the “Additional Board Manager URLs” field as shown in the figure below. Then, click the “OK” button:

    Installing ESP32 Add-on in Arduino IDE Windows, Mac OS X, Linux enter URLs

    Note: if you already have the ESP8266 boards URL, you can separate the URLs with a comma as follows:

    https://dl.espressif.com/dl/package_esp32_index.json, http://arduino.esp8266.com/stable/package_esp8266com_index.json
  3. Open the Boards Manager. Go to Tools > Board > Boards Manager…

    Installing ESP32 Add-on in Arduino IDE Windows, Mac OS X, Linux open boards manager
  4. Search for ESP32 and press install button for the “ESP32 by Espressif Systems“:

    ESP32 Add-on in Arduino IDE Windows, Mac OS X, Linux Installed
  5. That’s it. It should be installed after a few seconds.

    ESP32 Board add-on in Arduino IDE installed

Testing the Installation

Plug the ESP32 board to your computer. With your Arduino IDE open, follow these steps:

1. Select your Board in Tools > Board menu (in my case it’s the DOIT ESP32 DEVKIT V1)

Arduino IDE select the ESP32 board in Tools menu

2. Select the Port (if you don’t see the COM Port in your Arduino IDE, you need to install the CP210x USB to UART Bridge VCP Drivers):

Arduino IDE select the ESP32 Port in Tools menu

3. Open the following example under File > Examples > WiFi (ESP32) > WiFiScan

Arduino IDE open WiFiScan example for ESP32

4. A new sketch opens in your Arduino IDE:

Arduino IDE uploading WiFiScan example to ESP32

5. Press the Upload button in the Arduino IDE. Wait a few seconds while the code compiles and uploads to your board.

Arduino IDE upload WiFiScan sketch to ESP32

6. If everything went as expected, you should see a “Done uploading.” message.

Arduino IDE done uploading ESP32 WiFiScan sketch

7. Open the Arduino IDE Serial Monitor at a baud rate of 115200:

Open Arduino IDE Serial Monitor at baud rate 115200

8. Press the ESP32 on-board Enable button and you should see the networks available near your ESP32:

ESP32 Testing Add-on installation in Windows PC, Max OS X, and Linux computer

Troubleshooting

If you try to upload a new sketch to your ESP32 and you get this error message “A fatal error occurred: Failed to connect to ESP32: Timed out… Connecting…“. It means that your ESP32 is not in flashing/uploading mode.

Having the right board name and COM por selected, follow these steps:

  • Hold-down the “BOOT” button in your ESP32 board
Solved A fatal error occurred: Failed to connect to ESP32: Timed out… Connecting…
  • Press the “Upload” button in the Arduino IDE to upload your sketch:
Arduino IDE uploading new sketch to ESP32
  • After you see the  “Connecting….” message in your Arduino IDE, release the finger from the “BOOT” button:
Arduino IDE done uploading ESP32 WiFiScan sketch
  • After that, you should see the “Done uploading” message

That’s it. Your ESP32 should have the new sketch running. Press the “ENABLE” button to restart the ESP32 and run the new uploaded sketch.

You’ll also have to repeat that button sequence every time you want to upload a new sketch. But if you want to solve this issue once for all without the need to press the BOOT button, follow the suggestions in the next guide:

If you experience any problems or issues with your ESP32, take a look at our in-depth ESP32 Troubleshooting Guide.

Wrapping Up

This is a quick guide that illustrates how to prepare your Arduino IDE for the ESP32 on a Windows PC, Mac OS X, or Linux computer. If you encounter any issues during the installation procedure, take a look at the ESP32 troubleshooting guide.

Now, you can start building your own IoT projects with the ESP32!

Thanks for reading.


Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »

Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »


Enjoyed this project? Stay updated by subscribing our weekly newsletter!

69 thoughts on “Installing the ESP32 Board in Arduino IDE (Windows, Mac OS X, Linux)”

  1. Can you explain why Python and a whole load of command line stuff is required?

    It wasn’t necessary for the ESP8266, installing that into the Arduino IDE was just a case of entering an address into the additional boards manager URLs box under the preferences tab and it all happened.

    I thought ESP 32 was the same…

    Reply
    • Hi Duncan,
      At the moment the Arduino IDE requires Python to communicate with the ESP32.
      It’s not currently able to do upload scripts exclusively from the Arduino IDE, but it should work like it did for the ESP8266 in a near future.

      Thanks for asking,
      Rui

      Reply
  2. I keep getting the compile error below

    File “C:\Users\Engineering\Documents\Arduino-1.6.13\hardware\espressif\esp32/tools/esptool.py”, line 183

    print ‘%s’ % inst.CHIP_NAME

    ^

    SyntaxError: Missing parentheses in call to ‘print’

    Multiple libraries were found for “WiFi.h”
    Used: C:\Users\Engineering\Documents\Arduino-1.6.13\hardware\espressif\esp32\libraries\WiFi
    Not used: C:\Users\Engineering\Documents\Arduino-1.6.13\libraries\WiFi
    Using library WiFi at version 1.0 in folder: C:\Users\Engineering\Documents\Arduino-1.6.13\hardware\espressif\esp32\libraries\WiFi
    exit status 1
    Error compiling for board ESP32 Dev Module.

    Reply
    • That’s because it’s executing python3 which requires parenthesis for “print”, to solve this:
      – install python 2.7 (in c:\python27 for example)
      – add the it’s directory (c:\python27) to PATH environment variable
      – rename the python.exe located in the python 3 directory (c:\python36) to python3.exe

      Reply
  3. Hi Rui,

    I’m not very familiar with Arduino IDE so far. But I have installed the ESP8266-board-definitions.
    I don’t remember the exact process. Your tutorial misses how to add the ESP32-board definitions. I’m using Arduino IDE V1.6.12 which does not include ESP32. As a newbee I would have to re-install the newest Arduino-IDE. This would require a lot of additional adjustments.

    please add to this tutorial how the board -definition of the ESP32 can be added.

    best regards

    Stefan

    Reply
  4. Same thing with your link
    “The ESP32 is currently being integrated with the Arduino IDE just like it was done for the ESP8266, but not everything is working at the moment (see here).”

    linking right in the middle of github does newbees like me not help at all.
    I’m also a newbee to github.
    maybe you wait with your tutorial until the standard integration is done. Or at least add a first block of info telling what knowledge somebody should have to use your tutorial.

    I mean something like that:
    If you are familiar with Github and git and are not afraid of installing python you could already play with the ESP32

    best regards

    Stefan

    Reply
    • I agree with you Stefan, the ESP32 is not as easy as the ESP8266 to integrate with the Arduino IDE, but if you follow this exact tutorial you should be able to prepare your Arduino IDE with the ESP32 boards.
      When new instructions are available, I’ll update this tutorial.

      Thanks,
      Rui

      Reply
  5. Everything up to last get.py was smooth.
    On windows machine it seems to be missing a file named ‘requests’

    jim@maximus MINGW64 /c/Program Files (x86)/Arduino/hardware/espressif/esp32/tools (master)
    $ python get.py
    Traceback (most recent call last):
    File “get.py”, line 25, in
    import requests
    ModuleNotFoundError: No module named ‘requests’

    Reply
  6. Hi Rui,

    what are the steps that the arduino-IDE-developers have to take until the ESP32-support reaches the stage as described in the following:

    I’m not very familiar with the Arduino-IDE and specific terms and words. I hope it is still understandable what I want to ask

    1.) Download the ESP32-“plugin” (or is it called “board-manager-entry”?)
    2.) start arduino-IDE new
    3.) write code for the ESP32-based board
    4.) upload code to the board – code is running.

    I would like to use the Arduino-IDE like it is meant to be:
    choose your arduino-board from a list write and upload code.

    Maybe I sound like I want to make everybody to hurry up. I don’t mean so. I’m very thankful for all the coders that took great effort to make coding a µC-board through the Arduino-IDE so easy. It is just that I would like to have some information about this: What is your ESTIMATION

    will it take 6 weeks or maybe 3 months or will it take 24 months until ESP32-boards are fully supported by the Arduino-IDE?

    best regards

    Stefan

    Reply
  7. thanks ru very interested at the this time I’m using my phone?, a android s6 Samsung witch I use to switch my lid lighting on & off so very interested in this technology and as you know I like making projects like guitar pedals + I’m a radio am thanks again pete

    Reply
  8. Hi Thanks for the information. i am having problems cloning Git Gui. Something to do with permissions. Any suggestions how I fix this or cam I copy the relevant files?

    Reply
    • After a bit of fairly random key presses I got everything (well the program you demonstrate) to work. thank you. The pleasure on success far out-ways the frustration when everything fails

      Reply
  9. I got the espressif library put in the hardware directory for the Arduino, but the BLE directory is empty. Is it the same for the 8266, and/or where can I find it?

    Thanks

    Reply
  10. I followed the instructions for Installing the ESP32 Board in Arduino IDE, but it doesn’t communicate with the board. The port option is grayed out and I can’t select the port to use. I have this dev board: ezsbc.com/index.php/featured-products-list-home-page/wifi01-32.html#.WqL5pnXwblM

    When I try to upload, I get:
    “Failed to execute script esptool the selected serial port Failed to execute script esptool
    does not exist or your board is not connected”

    Reply
    • Hi Joel,
      As we’ve discusses in the Facebook group, if your board doesn’t appear in your Arduino IDE it’s a problem with your drivers.
      I would uninstall the drivers for your ESP32 built-in serial converter chip and try to install them again…

      Reply
  11. OK Found a solution that is currently working, although I’m not sure yet if anything else broke implementing it. I found when running the GET.EXE it added another sub-directory /arduino-esp32 under the espressif/esp32 directory path, and moved all the files into this subdirectory. Moving all the files back up to the esp32 directory has got it working, and I can load and run the suggested example. Not sure why the sub-directory is added, but it did it again after un-installing everything and starting again too.

    Reply
  12. You d’man, unless of course you are a girl, then you d’girl! I have had two of these in my parts box now since they came out, and never could get them running. I have been to dozens of sites with step-by-step instructions and although I can build a computer from scratch, and have done so, on a dare, and I have beat lawayers in court when acting as a paralegal, I could not get the blasted things to work. This one has guided me, and works great. The first unit I tried, both brand new, failed to work at all, and I thought, well just like the rest of the instructions, but just for shits and giggles, I grabbed my second unit, and IT WORKS!!!! Thanks a billion now I can have fun with my ESP32 as well as my ESP8266’s (I have about a dozen doing chores around my house and reporting back) and my Arduinos that are serving several devices I made for our RV to use when on the road, such as my home built GPS, my leveling device since the built in one only works once in awhile, and other little toys that make my wife of 48 years giggle when I press the buttons on my remotes.

    Reply
    • Me (Rui Santos) I’m a guy. But, if Sara Santos answers a question (she’s a girl).

      I’m glad this tutorial worked out for you! Thanks for letting me know!
      Regards,
      Rui

      Reply
  13. When I open the get.exe it opens a commandscreen and then it doesn’t do anything anymore. Do I just have to wait a very long time or did I do something wrong?

    Reply
  14. I followed this excellent how-to to the end and everything appeared to be ok. Went into IDE and selected COM6 (the ESP chose that), I’m using the ESP module you used above.

    But when I try to download a sketch I get

    onnecting…….._____….._____….._____….._____…..__….._____….._____….._____

    A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header

    Any suggestions

    Reply
    • Hi George.
      When that happens, you need to hold-down the “BOOT” button in your ESP32 board while the code is uploading.
      After you see the “Connecting….” message in your Arduino IDE, release the finger from the “BOOT” button.
      This should solve your problem.
      You may also want to take a look at the ESP32 troubleshooting guide: https://randomnerdtutorials.com/esp32-troubleshooting-guide/
      I hope this helps.
      Regards,
      Sara 🙂

      Reply
  15. Edit the “Sketchbook location” with forward slashes, so it looks as follows:

    C:/Users/ruisantos/Documents/Arduino

    how do i do that? sorry if it is a dumb question

    Reply
    • Simply replace it manually, if it looks like this:
      C:\Users\ruisantos\Documents\Arduino
      Remove those \ and replace with /

      C:/Users/ruisantos/Documents/Arduino

      I hope that helps.
      Regards,
      Rui

      Reply
  16. Thanks to your tutorial I finally got it working again – my Arduino IDE and the ESP32. Before I was really lost even I followed some other instructions in the Web. Your tutorials are so clearly clear and you never forget any step. And your layout earns an award!

    Reply
    • Thanks. We’re glad it works.
      Many users struggle to get the Arduino IDE working with the ESP32.
      We try to make the instructions as clear as possible, so that anyone can get it working.
      Regards,
      Sara 🙂

      Reply
  17. Hi Rui,

    I have a problem

    A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header

    From doing that to you. What is it? Installed the library? Or the board.

    Reply
  18. Hi,

    I’v got this board:
    banggood.com/Goouuu-ESP-32F-Development-Board-ESP32-Kit-Bluetooth-WiFi-IoT-Control-Module-For-Arduino-p-1357920.html?rmmds=search&ID=557197&cur_warehouse=CN

    I don’t have any specification for the TFT, Speaker output and the RGB Led.
    I was able to use the RGB led with trial and error, using the “ESP32 Wrover module” 😉
    I didn’t find a ESP-32F manager, just using the ESP-32 manager.

    Any idea for the rest?

    Thank you.

    Reply
    • Hi Dzandaa.
      I’ve never used that board. So, I don’t have any information about that.
      Maybe the best thing to do is trying to get some documentation or information from the vendor.
      I’m sorry that I can’t help.
      Regards,
      Sara 🙂

      Reply
  19. Rui,

    You also have to PUSH THE BOOT BUTTON while UPLOADING (at least on the DEVKIT V1) else you get an error:
    .
    “Failed to connect to ESP32: Timed out waiting for packet header”
    .
    Thanks!

    Reply
  20. Bonjour. j’ai utiliser votre sketch WiFi Scan avec l’Esp32.la compilation dure 5 Minutes et le CPU de W7 tourne à 100%.pourquoi? à vous lire.salutations. vos cours m’interesse,existet-ils en verion livres? car étant souvent en déplacement il m’est difficille de regarder les videos

    Reply
    • Hi Robert.
      I don’t understand french. I used the translator but didn’t understand your first question.
      Our ESP32 course is available both in video and eBook. When you buy the course, you get both versions.
      Regards,
      Sara 🙂

      Reply
  21. ..if anybody still have trouble uploading sketches to their WEMOS D1R1 or similar after CH341SER driver install & even with latest arduino
    ide with the ESP8266 PLATFORM downloaded connected to proper port in device manager Windows Xp or higher, with error message cxxabi_tweaks.h
    not present do this….copy cxxabi_tweaks.h from{ your drive]C:\Documents and Settings\{your pc name}\Local Settings\Application Data\Arduino15
    \packages\esp8266\tools\xtensa-lx106-elf-gcc\1.20.0-26-gb404fb9-2\xtensa-lx106-elf\include\c++\4.8.2\xtensa-lx106-elf\bits to C:\Documents and Settings
    \{your pc name}\Local Settings\Application Data\Arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\1.20.0-26-gb404fb9-2\xtensa-lx106-elf
    \include\c++\4.8.2\bits ….it took me a week to figure it out…finally the blink sketches worked…so i have a renewed my spirit for a wifi radio

    Reply
  22. Thank you this is an excellent guide and help. I only want to inform about a key item from my point of view:
    CP210x Driver Issue v10.1.4 on Windows 10 1809 : currently I did not found any solution for installing this driver working correctly with Arduino IDE; you do not will find the port ! Any solution ?

    Reply
  23. Hi Rui,
    Thanks for the instructions. I was having difficulties installing but when I wrote exactly what I had done I realised my mistake. Wow Do I feel stupid. I suggest to all those having difficulties that they write down exactly what they are doing and perhaps the problem will solve itself.

    Reply
  24. For those getting the error: “A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header”

    I ran into the same issue and couldn’t resolve for the life of me. Turns out I have been shipped (twice, now) an ESP8266 in an ESP32 packaging. Configuring for the ESP8266 solved my issue, naturally. Throwing this out there in case this same thing happened to others.

    Reply
  25. I finally got an ESP32. (Better late than never). I tried using this instructional to get it up and running. The board is a Node32s. I can see the port in the IDE; but when I try it upload the example sketch, I get an error that says it failed to connect to ESP32: Timed out waiting for packet header. Any thoughts?

    Reply
  26. My Boards Manager says that I have the “ESP32 by Expressif Systems” version 1.0.2 installed.
    But I don’t see the ESP32 *anything in the boards manager.

    Any tips? Do I need to go back to version 1.0.1 in my Boards Manager?

    Reply
  27. Cumprimentos Sara e/ou Rui. Primeiramente, obrigado pelo tutorial; no entanto, tenho uma questão um tanto diferente:
    Qualquer sketch feito para a plataforma Arduino, é possível usá-lo com o esp32 ou esp8266? Se não, o que deve ser mudado e/ou acrescentado no código para tal? Muito obrigado

    Reply
    • Hi Daniel.

      Next time, try to post your questions in English so that all our readers can understand.

      An Arduino sketch can be used for the ESP32 with some changes. There are a few things that you need to be aware of:
      – if you’re using libraries, they should be compatible with the ESP32
      – the pins used in Arduino are different in the ESP32
      – there are some functions in the Arduino that are different on the ESP32. For example, analogWrite() doesn’t work with the ESP32
      – the input range of analogRead() of Arduino UNO is 0 to 1023, while on the ESP32 is 0 to 4095
      There are also other small details you need to take into account when adapting an Arduino code to work with the ESP32.

      I hope I’ve answered your question.

      Thank you for following our work.

      Regards,
      Sara

      Reply
  28. Hi Sara and Rui,

    The sketch uploads but I keep getting this repeating message in the Serial Monitor:

    rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
    configsip: 0, SPIWP:0xee
    clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
    mode:DIO, clock div:1
    load:0x3fff0018,len:4
    load:0xffffffff,len:-1
    ets Jun 8 2016 00:22:57

    rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
    configsip: 0, SPIWP:0xee
    clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
    mode:DIO, clock div:1
    load:0x3fff0018,len:4
    load:0xffffffff,len:-1
    ets Jun 8 2016 00:22:57

    I am using the latest Arduino IDE version 1.8.9. and I am using a Node MCU ESP 32. I am using I2C the serial protocol and have wired correctly to the CLK and SDI pins. I am using a MacBook Pro.

    When I loaded your code to my Arduino Uno, the code ran fine.

    Reply
  29. Hi Sara,

    So I have the ESP32 DEVKIT V1 30 pin development board. I selected the ESP32 DEVKIT V1 board and when I plugged it into the PC COM28 popped up. So I selected it.

    “esptool.py v2.6
    Serial port COM28
    Connecting…….._____….._____….._____….._____….._____….._____…..____An error occurred while uploading the sketch
    _

    A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header”

    This is the error message that I received. I then tried holding the BOOT button down until I saw the “Connecting…” message and released the BOOT button, but the same error then popped up.

    Any further suggestions?

    Reply
    • If that fix doesn’t work – I always hold the rst and boot button together, then release the rst, wait 1 second, and release the boot – all after the Connecting prompt and as the ….____ part comes up.

      Reply
  30. Hi Rui,
    Thanks for your great work and website, for me the best tutorials on Arduino, an ESP. Clear, and complete and working, you ebook too, the best I gave seen on the net and I’am in the electronic business about 50 years now.
    Have some ESP32 devices since a log time, but had troubles on my mac when compiling, like many others. I’am now on 10.14.6 and tried once agin, it works 🙂 I followed your tutorial Above. But one thing, the DOITESP32 DEVKIT V1 ist not shown. I Installed the same board library as you and even newer ones. I than the ESP 32 Dev Module. The WiFi Scan sample works. Will I be able to get all out of my ESP32 even when there is an other board selected or how can I get the right board.

    Rainer

    Reply
  31. Hi. i’ve followed all the steps and all went fine.
    BUT my AI Tinker ESP32-Cam doesn’t hace a ENABLE button!!!
    Only the RESET one!

    Some clue?

    Reply
      • Hi Sara, ok but when i upload the sketch all goes fine ending with the text you can see bellow. The i push the reset button and the serial console shows:

        rst:0x1 (POWERON_RESET),boot:0x3 (DOWNLOAD_BOOT(UART0/UART1/SDIO_REI_REO_V2))
        waiting for download

        and nothing more…

        SKETCH LOAD:
        Writing at 0x00008000… (100 %)
        Wrote 3072 bytes (119 compressed) at 0x00008000 in 0.0 seconds (effective 1068.5 kbit/s)…
        Hash of data verified.

        Leaving…
        Hard resetting via RTS pin…

        Reply

Leave a Reply to Stefan Ludwig Cancel reply

Download our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.