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:
In your Arduino IDE, go to File> Preferences
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:
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
Open the Boards Manager. Go to Tools > Board > Boards Manager…
Search for ESP32 and press install button for the “ESP32 by Espressif Systems“:
That’s it. It should be installed after a few seconds.
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)

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):

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

4. A new sketch opens in your Arduino IDE:

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

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

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

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

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

- Press the “Upload” button in the Arduino IDE to upload your sketch:

- After you see the “Connecting….” message in your Arduino IDE, release the finger from the “BOOT” button:

- 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!
- Learn ESP32 with Arduino IDE [eBook + Video Course]
- ESP32 vs ESP8266 – Pros and Cons
- Free ESP32 Projects and Tutorials
- Build an ESP32 Web Server with Arduino IDE
- ESP32 DHT11/DHT22 Web Server with Arduino IDE
Thanks for reading.
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…
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
Thank you very much. I learn something from you.
Mendis.
You’re welcome,
Rui
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.
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
Found my error, I had both 2.7 and 3.6 Python versions. I unloaded 3.6 and made sure 2.7 and in path. Thanks
I’m glad you found the solution, thanks for sharing it with us!
Rui
Thanks for this interesting item, i made it working in the IDE.
Now i have to wait for an ESP 32.
Happy New Year and Merry Chrismas.
You’re welcome,
More tutorials with this board very soon.
Rui
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
Hi Stefan,
This post describes the exact process adding the ESP32 board to your Arduino IDE installation.
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
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
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’
pip install requests
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
Fails with error:
“C:\\Program Files (x86)\\Arduino\\hardware\\espressif\\esp32/tools/xtensa-esp32-elf/bin/xtensa-esp32-elf-g++”: file does not exist
Follow the steps as Rui says , just run GET as admin in Windows , it worked for me.
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
Thanks for reading. You could apply to that project, but I don’t have any information on that specific requirement.
Regards,
Rui
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?
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
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
The ESP8266 doesn’t have BLE (or Classic Bluetooth).
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”
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…
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.
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.
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
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?
After that, can you see the ESP32 boards available in the Arduino IDE after closing the get.exe file?
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
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 🙂
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
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
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!
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 🙂
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.
Make sure you hold down the BOOT button to force your ESP32 into flashing mode
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.
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 🙂
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!
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
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 🙂
..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
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 ?
Hi Michael.
I’ve never faced that error and I haven’t find much information about that. Only the following link:
https://www.silabs.com/community/interface/forum.topic.html/cp210x_driver_issue-DhIE
If anyone knows a solution for this, please share with us.
Regards,
Sara 🙂
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.
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.
Hi Peter.
I’m sorry for that issue. Where did you order your “ESP32” boards?
You can solve that issue by following this tutorial: https://randomnerdtutorials.com/solved-failed-to-connect-to-esp32-timed-out-waiting-for-packet-header/
Regards,
Sara
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?
Hi John.
Please describe the instructions in this tutorial to be able to upload code:
https://randomnerdtutorials.com/solved-failed-to-connect-to-esp32-timed-out-waiting-for-packet-header/
Regards,
Sara
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?
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
And for those of us (I suspect, the majority) who don’t read Portuguese???
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
Hi I just read this excellent tutorial but I have a problem where in the board manager it says “error: can’t download https://dl.espressif.com/dl/package_esp32_index.json” and can’t search for the esp32 in the search bar there… Please help
Hi.
That happened to me a few days ago.
The solution was to unnistall Arduino IDE and install again.
Then, install the ESP32 add-on.
Regards,
Sara
Installing 1.8.9 resolved the problem. Make sure you put the new library source under your preferences, Additional Boards Manager box (shown above in blue, if you have a 8266 one already there separate by commas). So it should read “https://dl.espressif.com/dl/package_esp32_index.json, http://arduino.esp8266.com/stable/package_esp8266com_index.json” – without the double quotes.
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.
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?
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.
Nevermind. Hardware problem in my circuit. Thanks 🙂
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