SDK upgrade guide
ESP-IDF 5.5 to ESP-IDF 6.0: what needs attention
Migratorisk's knowledge base lists 62 documented changes between ESP-IDF 5.5 and ESP-IDF 6.0. 56 of them are rated likely to break code, configuration or builds that use them. Below is each change, what a scan also reviews on this path, and how to see which ones apply to your project.
Find which of these affect your firmware
Migratorisk scans your project on your own computer and reports only the changes your code, configuration and build actually touch. Your source code is not uploaded.
python -m pip install migratorisk migratorisk scan --project ./your-firmware --from esp-idf-5.5.0 --to esp-idf-6.0.0 --out report.html
Requires Python 3.12 or newer. Results are free and complete without sign-up; sharing a report with us is optional.
Set up the local scanOr answer a few questions insteadWhere the changes are
What changes between ESP-IDF 5.5 and ESP-IDF 6.0
Ordered by impact. Each item names the release that introduced it and links to the official source. A change only matters if your project uses what changed; the scan checks that.
Wi-Fi: Removed Variables, Macros and Enum Values
Wi-Fi: Removed Variables, Macros and Enum Values Covers 18 names.
Networking: Ethernet: Ethernet PHY and Ethernet SPI Module drivers are moved from ESP-IDF to external repo
The Ethernet PHY and Ethernet SPI Module drivers have been removed from ESP-IDF and have been migrated to `esp-eth-drivers <https://github.com/espressif/esp-eth-drivers>`_ repository. If you are using these drivers, you need to use the drivers as component in your project. Covers 11 names.
System: Time
System: Time Covers 11 names.
Peripherals: LCD
Peripherals: LCD Covers 10 names.
Wi-Fi: Removed Functions and Types
The following functions and types have been removed. Covers 8 names.
Security: Mbed TLS
Starting from **ESP-IDF v6.0**, some already deprecated mbedtls header files like esp32/aes.h, esp32/sha.h, esp32s2/aes.h, esp32s2/sha.h and esp32s2/gcm.h have been removed. Please use aes/esp_aes.h, sha/sha_core.h and aes/esp_aes_gcm.h instead. The SHA module headers sha/sha_dma.h and sha/sha_block.h are also deprecated and removed. Covers 7 names.
Security: PSA Crypto migration: Mbed TLS v4.0 migration
ESP-IDF v6.0 updates to Mbed TLS v4.0, where **PSA Crypto is the primary cryptography interface** (TF-PSA-Crypto provides cryptography; Mbed TLS focuses on TLS and X.509). This can impact applications directly using Mbed TLS cryptography primitives, TLS configuration, or Mbed TLS internal/private declarations. Covers 7 names.
Bluetooth Classic: Bluedroid
The following Bluedroid APIs have been deprecated and removed: The following Bluedroid API have been changed: Covers 6 names.
Peripherals: SPI Flash Driver
Peripherals: SPI Flash Driver Covers 6 names.
Networking: LWIP: Ping API Removal
The deprecated ping APIs and headers have been removed in IDF v6.0: Applications should now use the socket-based ping API from ping/ping_sock.h: #include "ping/ping_sock.h" // Create ping session esp_ping_config_t config = ESP_PING_DEFAULT_CONFIG(); config.target_addr = target_ip; esp_ping_callbacks_t cbs = { .on_ping_success = on_ping_success, .on_ping_timeout = on_ping_timeout, .on_ping_end =... Covers 5 names.
Peripherals: DMA Driver
Peripherals: DMA Driver Covers 5 names.
Peripherals: I2S
Peripherals: I2S Covers 5 names.
Peripherals: LEDC
Peripherals: LEDC Covers 5 names.
Peripherals: I2C Slave Driver Updates: Major Changes in Usage
Peripherals: I2C Slave Driver Updates: Major Changes in Usage Covers 4 names.
Peripherals: Legacy I2S Driver is Removed
Peripherals: Legacy I2S Driver is Removed Covers 4 names.
Protocols: ESP-TLS: Unified Private Key Interface
The use_secure_element field in esp_tls_cfg, esp_tls_cfg_server, and httpd_ssl_config is deprecated and no longer functional: setting it to true makes the connection (or server start) fail with ESP_ERR_NOT_SUPPORTED. The field is kept only for source compatibility and will be removed in the next major release. Covers 4 names.
System: HW-Support
The deprecated soc_memory_types.h header file has been removed. Please include the replacement esp_memory_utils.h instead. The deprecated intr_types.h header file has been removed. Covers 4 names.
Wi-Fi: Modified Functions and Types
The following Wi-Fi functions have been modified. Covers 4 names.
Peripherals: GPIO
Peripherals: GPIO Covers 3 names.
Peripherals: SDMMC
Peripherals: SDMMC Covers 3 names.
Protocols: ESP-TLS: Removed wolfSSL Support
The built-in wolfSSL TLS stack support has been removed from ESP-TLS. Covers 3 names.
Security: Bootloader Support
**Deprecated APIs** The following function has been deprecated: **Secure Boot ECDSA curve selection** **Removed Deprecated APIs** The following deprecated functions have been removed: Covers 3 names.
Security: PSA Crypto migration: Removed deprecated APIs (Mbed TLS / crypto)
The following deprecated functions have been removed: Note that the new AES functions return error codes for better error handling, unlike the old void functions. Covers 3 names.
Storage: Breaking Changes
Deprecated esp_vfs_fat_sdmmc_unmount function is now removed. Please use esp_vfs_fat_sdcard_unmount instead. Function prototype for esp_vfs_fat_register has been changed to match esp_vfs_fat_register_cfg function. esp_vfs_fat_register_cfg is now deprecated. Covers 2 names.
Storage: VFS
Storage: VFS Covers 2 names.
System: App Trace: Configuration Changes
The application tracing configuration menu has been moved. Previously located at Component config > Application Level Tracing, it is now under Component config > ESP Trace Configuration. Previously, application tracing was automatically enabled when a destination was configured. Covers 2 names.
System: FreeRTOS: Removed Configuration Options
The following hidden (and always true) configuration options have been removed: Covers 2 names.
System: Log: Removed Functions
The following deprecated Log functions have been removed in ESP-IDF v6.0: Covers 2 names.
System: OTA Updates: Removed Deprecated APIs
The following deprecated functions have been removed from the app_update component: These functions have moved to the esp_app_format component. Update your include from esp_ota_ops.h to esp_app_desc.h and add esp_app_format to your component dependencies if needed. Covers 2 names.
Networking: ESP-NETIF: DHCP Server DNS Option Behavior
The LWIP_DHCPS_ADD_DNS macro has been removed. Previously, when running a DHCP server on SoftAP, if no DNS offer option was set, the server IP address was automatically advertised as the DNS server. **Current behavior:** From this release onward, the DHCP server includes DNS information in its offers only when explicitly configured using esp_netif_dhcps_option with the ESP_NETIF_DOMAIN_NAME_SERVER option.
Networking: ESP-NETIF: Removed Deprecated esp_netif_next
The deprecated iteration helper esp_netif_next has been removed from /api-reference/network/esp_netif. This API was inherently unsafe because it did not lock the interface list or the TCP/IP context during iteration. Use one of the following alternatives:
Networking: LWIP: SNTP Header File Removal
The deprecated sntp.h header file has been removed in IDF v6.0. Applications should now include esp_sntp.h instead of sntp.h for SNTP functionality.
Peripherals: ADC
The legacy ADC driver driver/adc.h is deprecated since version 5.0 (see deprecate_adc_driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_adc, and the header file path is esp_adc/adc_oneshot.h, esp_adc/adc_continuous.h, esp_adc/adc_cali.h and esp_adc/adc_cali_scheme.h.
Peripherals: Common Changes: Legacy Driver Dependencies Removal
The legacy driver component driver has been deprecated and no longer contains public dependencies on the following driver components: If your project uses legacy driver component, it is strongly recommended to remove driver component dependencies, and add new driver component (usually esp_driver_xxx) dependencies to your project.
Peripherals: Common Changes: Peripheral Clock Gating
Peripheral clock gating is managed within the driver layer. Users do not need to manually handle peripheral module clock gating. Its corresponding APIs are included via a private header file esp_private/periph_ctrl.h.
Peripherals: Common Changes: RTC Subsystem Control
Low power modules usually share some common resources like interrupt number. To avoid conflicts, some private APIs are created in the esp_private/rtc_ctrl.h header file to manage these shared resources with ease. There used to be another header file driver/rtc_cntl.h for the same purpose, which is now removed.
Peripherals: GPIO: GPIO Deep Sleep Wakeup APIs Removed
The following GPIO driver APIs have been removed: The deprecated macro GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO() has been removed.
Peripherals: Legacy DAC Driver is Removed
The legacy DAC driver driver/dac.h is deprecated since version 5.1 (see deprecate_dac_legacy_driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_dac, and the header file path is driver/dac_oneshot.h, driver/dac_continuous.h and driver/dac_cosine.h.
Peripherals: Legacy PCNT Driver is Removed
The legacy PCNT driver driver/pcnt.h is deprecated since version 5.0 (see deprecate_pcnt_legacy_driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_pcnt, and the header file path is driver/pulse_cnt.h.
Peripherals: Legacy RMT Driver is Removed
The legacy RMT driver driver/rmt.h is deprecated since version 5.0 (see deprecate_rmt_legacy_driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_rmt, and the header file path is driver/rmt_tx.h, driver/rmt_rx.h and driver/rmt_encoder.h.
Peripherals: Legacy Sigma-Delta Modulator Driver is Removed
The legacy Sigma-Delta Modulator driver driver/sigmadelta.h is deprecated since version 5.0 (see deprecate_sdm_legacy_driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_sdm, and the header file path is driver/sdm.h.
Peripherals: Legacy Temperature Sensor Driver is Removed
The legacy temperature sensor driver driver/temp_sensor.h is deprecated since version 5.0 (see deprecate_tsens_legacy_driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_tsens, and the header file path is driver/temperature_sensor.h.
Peripherals: Legacy Timer Group Driver is Removed
The legacy timer group driver driver/timer.h is deprecated since version 5.0 (see deprecate_gptimer_legacy_driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_gptimer, and the header file path is driver/gptimer.h.
Peripherals: MCPWM: Legacy MCPWM Driver is Removed
The legacy MCPWM driver driver/mcpwm.h is deprecated since version 5.0 (see deprecate_mcpwm_legacy_driver). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the esp_driver_mcpwm, and the header file path is driver/mcpwm_prelude.
Peripherals: PSRAM
Deprecated header file esp_spiram.h has been removed. Please use esp_psram.h instead.
Peripherals: UART
Peripherals: UART
Protocols: ESP-TLS: Removed Deprecated API
The deprecated esp_tls_conn_http_new function has been removed. Use either: The new API requires you to create the esp_tls_t structure using esp_tls_init and provides better control over the connection process.
System: App Trace: API Changes
The destination parameter has been removed from all apptrace APIs. Default destination is now configured in menuconfig under Component config > ESP Trace Configuration > Application Level Tracing and can be altered at runtime by providing callback with custom tracing configuration.
System: Bootloader
Removed option for compiling bootloader with no optimization level (-O0, `CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_NONE`). On most targets it was no longer possible to compile the bootloader with -O0, as IRAM sections would overflow. For debugging purposes, it is recommended to use the -Og (CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG) optimization level instead.
System: Core Dump
Binary data format has been dropped. `CONFIG_ESP_COREDUMP_DATA_FORMAT_BIN` is no longer supported. ELF is now the default data format. CRC data integrity check has been dropped. `ESP_COREDUMP_CHECKSUM_CRC32` is no longer supported.
System: FreeRTOS: Memory Placement
System: FreeRTOS: Memory Placement
System: Power Management
In previous versions of ESP-IDF, the API esp_sleep_get_wakeup_cause was used to retrieve the wakeup reason after the chip exited sleep. However, this function only returns one wakeup source, even if multiple sources were triggered simultaneously, which may cause users to miss other active wakeup events. Since ESP-IDF v6.0, a new API esp_sleep_get_wakeup_causes has been introduced.
System: Ring Buffer: Memory Placement
To reduce IRAM usage, the default placement for `esp_ringbuf` functions has been changed from IRAM to Flash. Consequently, the CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact.
System: System Console (STDIO)
esp_vfs_cdcacm.h has been moved to the new component esp_usb_cdc_romconsole, you will now have to add an explicit REQUIRES for esp_usb_cdc_rom_console if using any functions from this header.
System: Xtensa
The Xtensa special register header files have been updated to use a new naming convention. The old specreg.h header files are now deprecated and will be removed in a future release. The register names have been updated to use the XT_REG_ prefix.
System: esp_common
System: esp_common
Peripherals: SPI Flash Driver: Header File Reorganization
Several internal header files have been reorganized to better reflect their visibility and intended usage: The headers in esp_flash_chips/ are **semi-public** - they are intended for expert users who need to implement custom chip drivers for unsupported flash chips, but they are **not considered stable API** and may change without notice. For most use cases, you should use the public APIs in esp_flash.h instead. Covers 3 names.
Peripherals: Color Types
The following types in the components/hal/include/hal/color_types.h header file have been removed. Please use FourCC format (esp_color_fourcc_t) instead: Migration example: /* Old */ color_space_pixel_format_t format = { .color_space = COLOR_SPACE_RGB, .pixel_format = COLOR_PIXEL_RGB565 }; /* New */ esp_color_fourcc_t format = ESP_COLOR_FOURCC_RGB565; Covers 2 names.
Networking: Ethernet: PTP API Changes
Ethernet `esp_eth_ioctl` PTP configuration and control commands have been removed. **Removed ioctl Commands**: **Impact**: Applications using the removed ioctl commands will no longer work. **Migration**: Use the new PTP API instead.
Peripherals: MCPWM
The io_od_mode member in the mcpwm_generator_config_t configuration structure has been removed. If you want to use open-drain mode, you need to manually call the gpio_od_enable function. The pull_up and pull_down members have been removed from the following configuration structures.
And 2 more changes, all checked by the scan.
What a scan of this path also reviews
Beyond the documented changes, Migratorisk reviews these upgrade risks for ESP-IDF projects on this path. Each one is reported only when the project shows the trigger.
Devices in the field keep their old bootloader after an OTA update
When it applies: The project updates over the air, which replaces the application but not the second-stage bootloader.
Why it matters: Major releases change bootloader and image-format defaults; the new application must still boot from the bootloader already on each device, or the update bricks it.
What to do: Test the new application booting from the bootloader built with the current production ESP-IDF, including rollback if CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE is used. Check the bootloader compatibility notes for the target release.
Managed components must support the target ESP-IDF
When it applies: The project depends on components from the ESP Component Registry (idf_component.yml).
Why it matters: Each component declares the ESP-IDF versions it supports. Old pinned versions may not build with the new release, and newer versions can change their own APIs.
What to do: Check each dependency's supported ESP-IDF range, update version constraints, then regenerate dependencies.lock and review the changes.
Arduino core is used as an ESP-IDF component
When it applies: The project builds the Arduino core (arduino-esp32) as an ESP-IDF component.
Why it matters: Each Arduino core release supports only a specific ESP-IDF version. Upgrading ESP-IDF without a matching Arduino core release fails to build.
What to do: Pick the arduino-esp32 release that matches the target ESP-IDF version first, then upgrade both together.
Updated firmware must still fit the OTA slots of devices in the field
When it applies: The project ships firmware updates over the air into fixed OTA slots defined by its partition table.
Why it matters: Major releases remove legacy drivers and change system libraries, often growing the application noticeably; the partition table on deployed devices cannot follow.
What to do: Keep the partition table byte-for-byte identical for devices already deployed, and check the new application size against the smallest OTA slot after the first build.
Small application partition leaves little room for a larger ESP-IDF
When it applies: The smallest application partition is under 1.5 MB.
Why it matters: Newer ESP-IDF releases and toolchains often grow the application binary (Wi-Fi, Bluetooth, TLS and libc changes). If it no longer fits, the build fails or OTA updates are rejected, and the partition table cannot be changed on deployed devices without a risky migration.
What to do: Build with the target ESP-IDF early and compare the binary size with the partition. Plan size optimisations (CONFIG_COMPILER_OPTIMIZATION_SIZE, unused features off) before committing to the upgrade.
The application already nearly fills its partition
When it applies: The current build leaves less than 15% free space in the smallest application partition.
Why it matters: Any growth from the upgrade can make the image too large for the partition, which fails the build or the OTA update.
What to do: Measure the size with the target ESP-IDF first; reduce size or plan a partition-table migration before the upgrade.
A major ESP-IDF upgrade removes legacy drivers and APIs
When it applies: The selected path crosses a major ESP-IDF release.
Why it matters: Major releases remove APIs that were deprecated in the previous major line (legacy drivers, old headers and Kconfig options), change component dependencies and update FreeRTOS, networking and Bluetooth stacks. Code changes and full re-testing are expected.
What to do: Work through the migration guide of every major and minor release in the path, starting with build errors, then deprecation warnings, then behaviour changes on hardware.
Secure Boot or flash encryption is enabled
When it applies: The project enables Secure Boot, signed applications or flash encryption.
Why it matters: These settings are tied to eFuses already burned on deployed devices. A changed signing scheme, key or encryption mode makes updates fail or bricks devices, and mistakes cannot be undone on hardware.
What to do: Keep signing keys, scheme and flash-encryption mode identical to production. Test the full update path on a device with production eFuses before release.
The project keeps a full sdkconfig
When it applies: The project folder contains a complete sdkconfig (kept in version control or generated by earlier builds).
Why it matters: On the first build with a new ESP-IDF, renamed options are migrated automatically, but removed options are dropped and new options get defaults, quietly changing behaviour. The diff is easy to miss in a large file.
What to do: After the first build with the target version, review the sdkconfig diff line by line. Keep intentional settings in sdkconfig.defaults so they survive future upgrades.
New compiler version and warnings
When it applies: Major ESP-IDF releases move to a newer GCC and C library and tighten warnings.
Why it matters: New GCC versions add warnings and stricter checks. Code that built cleanly can fail where warnings are treated as errors, and undefined behaviour can surface at run time.
What to do: Build all targets and configurations with the target ESP-IDF, fix new warnings rather than silencing them, and rerun device tests.
VelocityCreate
Want us to handle the upgrade?
VelocityCreate can review your assessment, agree on the migration scope, and carry out the firmware changes and agreed verification. Discuss your deadline, hardware, and requirements with an embedded engineer.
Discuss my migrationBook a technical callThe initial discussion is free. Implementation is quoted separately.
Related upgrade paths
Generated from the rule catalog of Migratorisk 0.3.0. This is an automated summary of published SDK changes, not a review of your project, and it does not replace builds and device tests. How the scanner is validated.