Choosing your tools
Arduino IDE, PlatformIO, or ESP-IDF. They compile the same code for the same chip — what differs is how much of the build you own, and whether any of it is written down.
The three, and who each is for
Arduino IDE if you are starting. Two menus and one button, every library one dialog away, and nothing written down. It is not a toy — plenty of shipped products were built in it — but the configuration lives in your menus, so it cannot travel and it cannot be reviewed.
PlatformIO the moment a project has a second person, a second machine, or a
version you need to reproduce. Same compiler underneath; the difference is that
platformio.ini says which one.
ESP-IDF when you need something Arduino does not expose — a FreeRTOS setting, a peripheral driver with no wrapper, silicon that shipped last month. It is Espressif's own framework, and Arduino-for-ESP32 is a layer on top of it, so you are not leaving the platform, only the shortcuts.
Arduino C++ or MicroPython
This is a smaller decision than it looks, and it is not the same axis as the one above. Every article here is written in both.
C++ compiles to a binary that boots in milliseconds and uses the RAM you can account for. MicroPython runs an interpreter, so a line you type is a line that runs immediately — which is genuinely faster for exploring a sensor you have never used, and genuinely slower for everything you ship.
Most people end up in Arduino C++ for projects and drop into a MicroPython REPL to work out what a new module is doing. Nothing stops you doing both on the same board on the same afternoon; it is one reflash.
Do not install all three
They each want their own copy of the toolchain, the board packages and the serial driver, and having three means having three that disagree about which core version you are on. Pick one, finish something with it, and change later if the thing you needed was in another.
The code
This is the whole of a PlatformIO project's configuration. Every one of these lines is a decision the Arduino IDE also makes and does not record anywhere.
[env:esp32dev]
platform = espressif32@6.7.0
board = esp32dev
framework = arduino
monitor_speed = 115200
upload_speed = 921600
lib_deps =
bblanchon/ArduinoJson@^7.0.4
knolleary/PubSubClient@^2.8Commit this file and a colleague gets your build rather than their own — same core version, same library versions, same upload speed. That is the entire pitch.
MicroPython is a different arrangement again: you flash an interpreter onto the board once, and after that you are copying files onto a device that is already running.
# flash the interpreter, once per board
esptool.py --chip esp32 erase_flash
esptool.py --chip esp32 write_flash -z 0x1000 esp32-20260801.bin
# from then on, it is file copying
mpremote connect /dev/cu.usbserial-0001 fs cp main.py :main.py
mpremote connect /dev/cu.usbserial-0001 replmpremote is the official tool and it is the one worth learning. Thonny is friendlier for the first hour and hides exactly the things you will later need to see.
When it does not work
The board id in platformio.ini is not the marketing name. "ESP32 Dev Module" is `esp32dev`, an S3 devkit is `esp32-s3-devkitc-1`. Run `pio boards esp32` and copy the id from the first column rather than guessing.
Almost always different core versions. The IDE installs whatever is newest, PlatformIO installs whatever platform version you pinned. Set the same one in both, or accept that the pinned one is the truth.
Firmware builds differ per chip and per release. The C6 build gained Wi-Fi 6 flags in 1.25 and the P4 build still has no MIPI drivers. Check `help('modules')` in the REPL before you conclude your code is wrong.
Pick one and install it. Four things have to be present before a line of code can reach the board, and the errors do not name which one is missing.
Install the toolchain →Edit this page — content/esp32/choosing-your-tools.mdx
Discuss this article
Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.