Getting Started with ESP32 in Arduino IDE
Set up your ESP32 in Arduino IDE from scratch. This practical guide covers board package installation, board and port selection, your first upload, Serial Monitor testing, and fixes for the most common connection and upload problems.
The ESP32 is one of the easiest microcontrollers to start experimenting with once the software environment is configured correctly. It works well with Arduino IDE, supports Wi-Fi and Bluetooth on many variants, and is widely used for IoT devices, sensors, displays, automation projects, and prototypes.
The first setup, however, is slightly different from installing a standard Arduino board.
Arduino IDE does not include the full ESP32 board package by default, so you first need to add Espressif's board package, select the correct ESP32 target, and make sure the computer can communicate with the board over USB.
This guide walks through that process from a fresh Arduino IDE installation to uploading and verifying your first ESP32 sketch.
The first setup, however, is slightly different from installing a standard Arduino board.
Arduino IDE does not include the full ESP32 board package by default, so you first need to add Espressif's board package, select the correct ESP32 target, and make sure the computer can communicate with the board over USB.
This guide walks through that process from a fresh Arduino IDE installation to uploading and verifying your first ESP32 sketch.
What You Need
Before starting, prepare:
- An ESP32 development board
- A USB data cable
- A Windows, macOS, or Linux computer
- Arduino IDE
- An internet connection for downloading the ESP32 board package
The USB cable is worth mentioning specifically. A cable that can charge a phone is not necessarily capable of carrying USB data. A charge-only cable is one of the simplest reasons an ESP32 may power on but never appear as a serial device.
Arduino also recommends checking the USB cable first when a connected board is not detected.
Arduino also recommends checking the USB cable first when a connected board is not detected.
Step 1: Install Arduino IDE
Start by installing the current Arduino IDE.
Arduino IDE 2 is available for Windows, macOS, and Linux and provides the Boards Manager, Library Manager, Serial Monitor, board selector, and the normal compile/upload workflow in one application.
After installation, open the IDE once and allow it to complete any initial setup.
If you already use Arduino IDE for other boards, you do not need a separate installation for ESP32. ESP32 support is added as another board platform.
Arduino IDE 2 is available for Windows, macOS, and Linux and provides the Boards Manager, Library Manager, Serial Monitor, board selector, and the normal compile/upload workflow in one application.
After installation, open the IDE once and allow it to complete any initial setup.
If you already use Arduino IDE for other boards, you do not need a separate installation for ESP32. ESP32 support is added as another board platform.
Step 2: Add the ESP32 Board Package
The next step is telling Arduino IDE where to find Espressif's ESP32 platform package.
In Arduino IDE 2:
Windows / Linux
Go to:
File → Preferences
macOS
Go to:
Arduino IDE → Settings
Find Additional Boards Manager URLs.
Arduino allows third-party hardware manufacturers to provide a package index URL for their board platforms. Espressif provides one for the ESP32 family.
Use Espressif's current stable Arduino-ESP32 package index:
Espressif ESP32 stable Boards Manager package
Add it to Additional Boards Manager URLs, then save the Preferences window.
If another board-package URL is already there, do not delete it. Arduino IDE supports multiple package URLs.
In Arduino IDE 2:
Windows / Linux
Go to:
File → Preferences
macOS
Go to:
Arduino IDE → Settings
Find Additional Boards Manager URLs.
Arduino allows third-party hardware manufacturers to provide a package index URL for their board platforms. Espressif provides one for the ESP32 family.
Use Espressif's current stable Arduino-ESP32 package index:
Espressif ESP32 stable Boards Manager package
Add it to Additional Boards Manager URLs, then save the Preferences window.
If another board-package URL is already there, do not delete it. Arduino IDE supports multiple package URLs.
Step 3: Install the ESP32 Platform
Now open the Boards Manager.
You can either use the Boards Manager icon in the left sidebar or go to:
Tools → Board → Boards Manager
Search for:
esp32
Look for the package provided by Espressif Systems, then click Install.
Arduino IDE normally selects the latest available version by default. Unless an existing project specifically requires an older ESP32 Arduino Core, the current stable release is the sensible starting point.
The installation can take a few minutes because the package includes the compiler, board definitions, upload tools, libraries, and other files required to build ESP32 sketches. Arduino describes these files collectively as the board platform or core.
Once installation is complete, ESP32 boards should appear in the board-selection menu.
You can either use the Boards Manager icon in the left sidebar or go to:
Tools → Board → Boards Manager
Search for:
esp32
Look for the package provided by Espressif Systems, then click Install.
Arduino IDE normally selects the latest available version by default. Unless an existing project specifically requires an older ESP32 Arduino Core, the current stable release is the sensible starting point.
The installation can take a few minutes because the package includes the compiler, board definitions, upload tools, libraries, and other files required to build ESP32 sketches. Arduino describes these files collectively as the board platform or core.
Once installation is complete, ESP32 boards should appear in the board-selection menu.
Step 4: Connect the ESP32
Connect the ESP32 development board to the computer using a known-good USB data cable.
In Arduino IDE 2, click the board selector near the top of the window.
You should see one or more available serial ports.
Depending on the development board and USB interface, Arduino IDE may identify the board automatically, or the port may appear as an unknown device.
If Arduino IDE identifies it correctly, select it.
If it does not, choose:
Select other board and port
and manually select your ESP32 board.
Arduino distinguishes between the board and the port:
In Arduino IDE 2, click the board selector near the top of the window.
You should see one or more available serial ports.
Depending on the development board and USB interface, Arduino IDE may identify the board automatically, or the port may appear as an unknown device.
If Arduino IDE identifies it correctly, select it.
If it does not, choose:
Select other board and port
and manually select your ESP32 board.
Arduino distinguishes between the board and the port:
- The board selection determines how the sketch is compiled and uploaded.
- The port identifies the physical device connected to the computer.
Both must be correct for a normal upload.
Step 5: Select the Correct ESP32 Board
There are many ESP32-family devices, including the original ESP32 as well as ESP32-S2, ESP32-S3, ESP32-C3 and other variants.
Whenever possible, select the exact development board you are using.
For many generic ESP32 development boards based on the original ESP32-WROOM modules, ESP32 Dev Module is commonly used when there is no more specific board definition available.
Do not assume that every board labeled "ESP32" should use the same target.
Different variants may use different processors, flash configurations, USB interfaces, PSRAM configurations, and upload settings. Espressif specifically recommends knowing the characteristics of the target board before changing options in the Arduino IDE Tools menu.
For an initial test, leave most of the other Tools menu options at their defaults.
You usually do not need to change flash mode, partition scheme, CPU frequency, or upload speed just to verify that a normal development board is working.
Whenever possible, select the exact development board you are using.
For many generic ESP32 development boards based on the original ESP32-WROOM modules, ESP32 Dev Module is commonly used when there is no more specific board definition available.
Do not assume that every board labeled "ESP32" should use the same target.
Different variants may use different processors, flash configurations, USB interfaces, PSRAM configurations, and upload settings. Espressif specifically recommends knowing the characteristics of the target board before changing options in the Arduino IDE Tools menu.
For an initial test, leave most of the other Tools menu options at their defaults.
You usually do not need to change flash mode, partition scheme, CPU frequency, or upload speed just to verify that a normal development board is working.
Step 6: Upload a Simple Test Sketch
Before adding Wi-Fi libraries, sensors, displays, or other hardware, verify that the basic toolchain works.
Create a new sketch and use:
void setup() {
Serial.begin(115200);
delay(1000);
Serial.println("ESP32 setup is working.");
}
void loop() {
delay(1000);
}
Click Verify first.
If compilation succeeds, click Upload.
The IDE will compile the program and transfer it to the ESP32 through the selected serial port.
A successful upload confirms several things at once:
Create a new sketch and use:
void setup() {
Serial.begin(115200);
delay(1000);
Serial.println("ESP32 setup is working.");
}
void loop() {
delay(1000);
}
Click Verify first.
If compilation succeeds, click Upload.
The IDE will compile the program and transfer it to the ESP32 through the selected serial port.
A successful upload confirms several things at once:
- The ESP32 Arduino Core is installed
- The selected board definition can compile the sketch
- Arduino IDE can access the serial port
- The USB connection works
- The ESP32 can enter its flashing mode
- The firmware can be written to flash
This makes a simple sketch a useful first diagnostic step before moving on to a larger project.
Step 7: Check the Serial Monitor
After the upload completes, open the Serial Monitor.
Set its baud rate to:
115200 baud
Reset the ESP32 if necessary.
You should see:
ESP32 setup is working.
If you see readable output, your basic Arduino-ESP32 environment is ready.
If the output appears as random or unreadable characters, check that the Serial Monitor baud rate matches the value used in:
Serial.begin(115200);
Do not immediately assume that unreadable serial output means the board is defective. A baud-rate mismatch is often enough to explain it.
Set its baud rate to:
115200 baud
Reset the ESP32 if necessary.
You should see:
ESP32 setup is working.
If you see readable output, your basic Arduino-ESP32 environment is ready.
If the output appears as random or unreadable characters, check that the Serial Monitor baud rate matches the value used in:
Serial.begin(115200);
Do not immediately assume that unreadable serial output means the board is defective. A baud-rate mismatch is often enough to explain it.
If the ESP32 Does Not Appear as a Port
If the board powers up but Arduino IDE does not show a new port, start with the physical connection.
Try this sequence:
Try this sequence:
- Disconnect the ESP32.
- Check the available ports in Arduino IDE.
- Reconnect the board.
- Open the board selector or Tools → Port again.
- Look for the newly added port.
Arduino recommends this disconnect/reconnect comparison when an unidentified device is present.
If nothing changes, try another USB cable.
Then try another USB port on the computer.
Some ESP32 development boards also use separate USB-to-UART bridge chips. Depending on the board, the computer may require a driver for devices such as CP210x or CH340.
Check the actual USB interface fitted to your board rather than installing several random drivers at once.
If nothing changes, try another USB cable.
Then try another USB port on the computer.
Some ESP32 development boards also use separate USB-to-UART bridge chips. Depending on the board, the computer may require a driver for devices such as CP210x or CH340.
Check the actual USB interface fitted to your board rather than installing several random drivers at once.
If Upload Fails with "Failed to Connect"
A common ESP32 upload error looks similar to:
Failed to connect to ESP32
First confirm that the correct board and port are selected.
Then retry the upload.
Some ESP32 development boards handle reset and boot mode automatically. Others, particularly certain generic or custom boards, may require manual help entering the bootloader.
One common procedure is:
Failed to connect to ESP32
First confirm that the correct board and port are selected.
Then retry the upload.
Some ESP32 development boards handle reset and boot mode automatically. Others, particularly certain generic or custom boards, may require manual help entering the bootloader.
One common procedure is:
- Hold the BOOT button.
- Start the upload.
- Wait until the IDE begins attempting to connect.
- Release BOOT.
On boards with separate BOOT and EN/RESET controls, the exact sequence can vary.
Espressif's Arduino installation documentation also notes that some boards may require the boot button to be held during uploading.
If manual boot mode solves the problem every time, the board's automatic reset circuit or USB implementation may be worth investigating.
Espressif's Arduino installation documentation also notes that some boards may require the boot button to be held during uploading.
If manual boot mode solves the problem every time, the board's automatic reset circuit or USB implementation may be worth investigating.
If Arduino IDE Says No Upload Port Is Provided
This normally means the board definition has been selected, but no serial port has been assigned.
In Arduino IDE 2, open the board selector and choose the port associated with your ESP32.
You can also use:
Tools → Port
Arduino documents a missing port selection as the direct cause of the "no upload port provided" error.
In Arduino IDE 2, open the board selector and choose the port associated with your ESP32.
You can also use:
Tools → Port
Arduino documents a missing port selection as the direct cause of the "no upload port provided" error.
If the Wrong Board Is Selected
Selecting the wrong ESP32 variant can produce confusing results.
A sketch may fail to compile, upload incorrectly, reboot continuously, or expose options that do not match the hardware.
Open the board selector and choose:
Select other board and port
Then search for the exact board.
If you are using a generic development board, identify the ESP32 module or SoC printed on the board before choosing the target.
Do not select a board simply because its name looks similar.
Arduino IDE also allows a manually assigned board to override automatic identification, so if the IDE repeatedly shows an unexpected board, check whether a previous manual selection has been saved.
A sketch may fail to compile, upload incorrectly, reboot continuously, or expose options that do not match the hardware.
Open the board selector and choose:
Select other board and port
Then search for the exact board.
If you are using a generic development board, identify the ESP32 module or SoC printed on the board before choosing the target.
Do not select a board simply because its name looks similar.
Arduino IDE also allows a manually assigned board to override automatic identification, so if the IDE repeatedly shows an unexpected board, check whether a previous manual selection has been saved.
When Should You Change the ESP32 Core Version?
For a new project, starting with the current stable Arduino-ESP32 release is usually the simplest option.
For an existing project, upgrading deserves more care.
The ESP32 Arduino Core continues to evolve, and major versions can include API and framework changes. A project developed and tested with one core version should not automatically be assumed to behave identically after a major upgrade.
For a hobby experiment, updating and fixing problems as they appear may be acceptable.
For a product, classroom image, shared development environment, or long-lived project, recording the working core version is a much better habit.
That turns:
"it worked on my computer"
into a reproducible development environment.
The Arduino Boards Manager allows a specific version of an installed platform to be selected when necessary.
For an existing project, upgrading deserves more care.
The ESP32 Arduino Core continues to evolve, and major versions can include API and framework changes. A project developed and tested with one core version should not automatically be assumed to behave identically after a major upgrade.
For a hobby experiment, updating and fixing problems as they appear may be acceptable.
For a product, classroom image, shared development environment, or long-lived project, recording the working core version is a much better habit.
That turns:
"it worked on my computer"
into a reproducible development environment.
The Arduino Boards Manager allows a specific version of an installed platform to be selected when necessary.
A Simple Troubleshooting Order
When ESP32 setup fails, changing several settings at once usually makes troubleshooting harder.
A better order is:
A better order is:
- Check the USB cable
- Check the port
- Check the board selection
- Compile a minimal sketch
- Try manual BOOT mode
- Check the Serial Monitor baud rate
- Only then change advanced board settings
Arduino's own upload troubleshooting guidance follows the same general idea: verify the sketch, board, port, connection, reset behavior, and console output before moving into more specialized fixes.
Where to Go Next
Once the test sketch uploads and the Serial Monitor works, the ESP32 Arduino environment is ready for real projects.
From here you can begin experimenting with:
From here you can begin experimenting with:
- GPIO
- PWM
- ADC
- I²C
- SPI
- UART
- Wi-Fi
- Bluetooth
- Sensors
- OLED or TFT displays
- Web servers
- MQTT
- IoT platforms
Espressif maintains Arduino-specific documentation and examples for the ESP32 family, including basic GPIO tutorials and board configuration guidance.
The important part is to establish a known-good development environment first. If a basic compile, upload, and serial test works, later problems are much easier to separate into software, peripheral, wiring, or application-level issues.
The important part is to establish a known-good development environment first. If a basic compile, upload, and serial test works, later problems are much easier to separate into software, peripheral, wiring, or application-level issues.
Source and Extended Guide
This article is a condensed and re-edited version of a more detailed PCBCool technical guide.
The full version goes further into ESP32 core versions, partition configuration, command-line installation, upload troubleshooting, OTA updates, and production flashing.
Full guide: How to Install ESP32 in Arduino IDE — PCBCool
The full version goes further into ESP32 core versions, partition configuration, command-line installation, upload troubleshooting, OTA updates, and production flashing.
Full guide: How to Install ESP32 in Arduino IDE — PCBCool
Want to build a project?
Bring your design to life with the Elektor PCB Service, powered by Eurocircuits. Upload the project files and order professionally manufactured PCBs or assembled boards through a proven European production platform.
Supporting KiCad, Eagle, Gerber, and ODB++ formats, the service is suitable for everything from prototypes and validation builds to series production and volume manufacturing.
Made in Europe. Fast. Reliable. Professional.
Discussion (0 comments)