arduino-esp32: the Arduino core that puts ESP-IDF behind the Arduino API
Arduino core for the ESP32 family of SoCs
At a glance
- What is it?
- The espressif/arduino-esp32 core lets Arduino sketches compile for ESP32, ESP32-S3, ESP32-C6 and other Espressif SoCs, with each release pinned to a specific ESP-IDF version. It is the right layer for sketch-level firmware and the wrong one when you need ESP-IDF APIs directly.
- Who is it for?
- Adopt arduino-esp32 if your firmware is a sketch, your team already knows the Arduino API, and your target is one of the eight SoCs listed as stable in the README. Do not adopt it if you need ESP-IDF components that the core does not expose, if you target ESP32-C2 or ESP32-C61, or if you are still on a 2.x sketch and have not read the 2.x to 3.0 migration guide.
- Can I use it commercially?
- Yes, with conditions. LGPL-2.1 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 29, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What arduino-esp32 actually is, and who it is for
This repository is not a library you add to a sketch. It is the framework package that the Arduino IDE and arduino-cli download when you select an ESP32 board, published as framework-arduinoespressif32. It supplies the Wiring-style API (setup, loop, digitalWrite, Serial) on top of Espressif's own SDK, so a sketch written for an Arduino Uno can be recompiled for an ESP32 without touching the code. The description in package.json spells out the scope: "Arduino Wiring-based Framework for the Espressif ESP32, ESP32-P4, ESP32-S and ESP32-C series of SoCs".
The audience is anyone whose firmware is expressed as a sketch. Hobbyists moving from an 8-bit board, small product teams that want the Arduino library ecosystem, and educators who need a single toolchain across many boards. The README lists eight SoCs in the stable column: ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2, ESP32-P4, ESP32-S2 and ESP32-S3. The core is what makes the phrase "Arduino ESP32 board" mean anything at all: without it, the Arduino IDE has no idea what an ESP32 is.
How the core wraps ESP-IDF, and why the version pin matters
Each core release is tied to one ESP-IDF version, and the release titles say so. 3.3.12 is "based on ESP-IDF v5.5.5", as are 3.3.11; 3.3.10 was based on ESP-IDF v5.5.4. That pinning is the central architectural fact. The Arduino API is a translation layer, and the translation is written against a particular SDK. When you install core 3.3.12 you are also choosing ESP-IDF v5.5.5, whether or not you ever call into it.
The repository layout reflects the split. The top level holds boards.txt, platform.txt and programmers.txt, the files the Arduino build system reads to know which compiler flags and upload recipes apply to which board. The cores/ directory holds the Arduino API implementation, libraries/ holds the bundled libraries, variants/ holds per-board pin mappings, and package/ holds the packaging metadata. Kconfig.projbuild and idf_component.yml are the ESP-IDF side of the same tree, which is how the same source can be consumed either as an Arduino core or as an ESP-IDF component.
That dual identity is the interesting design choice. The README links an "Arduino as an ESP-IDF component" page, meaning you can drop the Arduino layer into an ESP-IDF project rather than the other way round. For teams that outgrow the sketch model but do not want to rewrite everything, that path exists. The README also notes that ESP32-C2 and ESP32-C61 are supported but "require using Arduino as an ESP-IDF component or rebuilding the static libraries", which is a concrete example of the wrapper not being the whole story.
Installing the ESP32 board and running a first sketch
The README points to an Installing page covering Windows, Linux and macOS, and it does not inline the steps. The usual route is the Arduino board manager, which consumes the package index published from this repository. In the Arduino IDE, open the board manager, search for esp32, and install the package; the version you get corresponds to a release such as 3.3.12. Command-line users do the equivalent through arduino-cli, adding the package index URL and then installing the core by name.
Once installed, the board list gains entries for every supported SoC. Selecting a board is what fixes the variant, and therefore the pin numbering. The README does not embed a pinout; it links the supported chips documentation page, and the repository's variants/ directory is the authoritative per-board mapping.
What a first sketch looks like is documented in the Getting Started page the README links, and the repository ships example sketches under libraries/ and idf_component_examples/ rather than in the README itself. The README gives no inline code sample, so the honest instruction is to open one of those bundled examples after selecting your board, compile it, and upload it. If the port does not appear, that is a driver or cable problem rather than a core problem; the README's Troubleshooting page is where it sends you.
For library work, the README links a Libraries page and an APIs page that explains compatibility with ESP8266 and with Arduino.cc's own core. That page is worth reading before assuming an existing library will behave identically, because the compatibility is documented rather than implied.
The 2.x to 3.0 migration is the real upgrade cost
The README carries a single bolded pointer to a migration guide for version 2.x to 3.x, and that link is the most important sentence in the file for anyone with existing firmware. A major version bump of the core is not a drop-in. Sketches written against 2.x may need edits before they compile against 3.x, and the guide exists precisely because the changes are not mechanical.
The practical consequence is that "upgrade the core" is a project, not a click. You are moving the Arduino API layer and the underlying ESP-IDF version at the same time. If your sketch depends on third-party libraries, those libraries also have to build against the new core. The README links an External Libraries Test page, which suggests the project tracks that surface, but a green upstream test says nothing about the specific library you pinned two years ago.
My read is that the release cadence makes this sharper than it sounds. Between 2026-06-05 and 2026-09-18 there were three releases: 3.3.10, 3.3.11 and 3.3.12. Staying current means touching your build regularly, and skipping several minor releases means crossing more ESP-IDF version changes at once. Pinning a core version and upgrading deliberately is the lower-risk posture.
Where the Arduino wrapper stops being the right tool
The clearest boundary is the one the README states itself. ESP32-C2 and ESP32-C61 are supported, but not through the plain board manager flow: they need Arduino as an ESP-IDF component or a rebuild of the static libraries. If one of those two chips is your target, you are not really an arduino-esp32 user in the ordinary sense.
The second boundary is API surface. The core exposes the Arduino API. Anything that only exists in ESP-IDF, or that the core has not wrapped, is out of reach unless you take the ESP-IDF component route. That route is documented, but it changes your project structure: you are now maintaining an ESP-IDF project that happens to include Arduino, with CMake and component dependencies, rather than a sketch.
The third boundary is debugging. The README's answer to a crash is EspExceptionDecoder, an external tool it links to for turning a raw exception trace into "meaningful call trace". That is a decode-after-the-fact workflow. If you need step debugging or a full ESP-IDF monitor, you are working against the grain of the sketch model. None of this makes the core deficient; it makes it a wrapper, and wrappers have edges.
Arduino core versus ESP-IDF directly
The real alternative is not another Arduino core. It is using ESP-IDF on its own, which is the SDK this project wraps. The difference in approach is structural rather than cosmetic. With arduino-esp32 you write setup and loop, and the core decides how the RTOS tasks, the event loop and the peripheral drivers are arranged. With ESP-IDF you write app_main, you configure FreeRTOS tasks yourself, and you call the drivers directly. You get the full API surface and the ESP-IDF build system, and you give up the Arduino library ecosystem and the single-file sketch.
The README treats this as a supported continuum rather than a fork: it documents Arduino as an ESP-IDF component and links a Lib Builder page for the C2 and C61 case. So the honest framing is that arduino-esp32 is the shallow end of the same pool. Choose it when the sketch model fits your problem. Move to ESP-IDF when you need control the wrapper does not expose, and expect the move to cost real time because your code shape changes, not just your includes.
A second comparison worth naming: the README links an APIs page explaining compatibility with ESP8266 and with Arduino.cc's core. If you are porting from an ESP8266 project, that page is the map. The two cores are related but not identical, and the documentation says so rather than leaving you to discover it.
Licence, releases and what maintaining a build costs
The repository is licensed LGPL-2.1, and package.json declares LGPL-2.1-or-later. That distinction is worth noticing if you ship firmware. The LGPL is a copyleft licence with a linking exception tradition, and how it applies to statically linked firmware images is a question for your own counsel; this article cannot answer it. What can be said from the files is that the licence identifier in package.json is the or-later form while the repository states LGPL-2.1, and that the LICENSE.md at the top level is the governing text.
Maintenance cost has two components. The first is the release cadence, which the release list shows is brisk: three releases between 2026-06-05 and 2026-09-18. The second is the version pinning. Every core release drags a specific ESP-IDF version with it, so an upgrade is two upgrades. The last push to the repository was on 2026-09-21, and the most recent release, 3.3.12, is dated 2026-09-18.
The upgrade path the README offers is the migration guide for 2.x to 3.x, plus the Roadmap project and monthly community meetings it links. There is no documented rollback procedure in the README: if a core upgrade breaks your build, the recovery is reinstalling the previous version through the board manager, which the README does not spell out. Budget for testing a core bump the way you would budget for a dependency major version, because that is what it is.
Editorial conclusion
Adopt arduino-esp32 if your firmware is a sketch, your team already knows the Arduino API, and your target is one of the eight SoCs listed as stable in the README. Do not adopt it if you need ESP-IDF components that the core does not expose, if you target ESP32-C2 or ESP32-C61, or if you are still on a 2.x sketch and have not read the 2.x to 3.0 migration guide. Before committing, verify three things: that your exact board appears in the supported chips table, that every external library you depend on builds against core 3.3.12, and that the ESP-IDF version behind that release, v5.5.5, matches what your other components expect.
Frequently asked questions
Can Arduino run ESP32?
Yes. arduino-esp32 is the Arduino core for the ESP32 family, so selecting an ESP32 board in the Arduino IDE installs this framework and lets a sketch compile for the chip. The README lists eight SoCs in the stable column, including ESP32, ESP32-S3 and ESP32-C6.
How do I install arduino-esp32?
The README points to an Installing page covering Windows, Linux and macOS rather than inlining the steps. The usual route is the Arduino board manager, where you search for esp32 and install the package; the version you receive corresponds to a release such as 3.3.12.
What is arduino-esp32?
It is the Arduino core for Espressif's ESP32 family, published as framework-arduinoespressif32. It provides the Arduino Wiring-based API on top of ESP-IDF, and each release is tied to a specific ESP-IDF version, such as 3.3.12 being based on ESP-IDF v5.5.5.
Is arduino-esp32 easier than Arduino?
The core keeps the same sketch model, so setup, loop and the familiar functions work unchanged; what changes is the toolchain behind them and the board selection. The README documents ESP8266 and Arduino.cc API compatibility on a dedicated page rather than claiming they are identical.
Is arduino-esp32 the same as ESP-IDF?
No. arduino-esp32 wraps ESP-IDF behind the Arduino API, and each core release pins one ESP-IDF version, such as 3.3.12 being based on ESP-IDF v5.5.5. The README also documents using Arduino as an ESP-IDF component, so the two can be combined rather than being mutually exclusive.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/espressif-arduino-esp32)