tool-esptoolpy@2.40900.0 unconditionally imports intelhex, causing ModuleNotFoundError for ESP32 builds

[ryandtracy]

Summary
After updating to platform = espressif32@6.12.0, PlatformIO installs tool-esptoolpy@2.40900.0. This version of esptool.py contains the following unconditional import:

from intelhex import HexRecordError, IntelHex

This causes builds to fail with:

ModuleNotFoundError: No module named 'intelhex'

—even when the project doesn't use .hex files and doesn't require intelhex.

Environment Details

• PlatformIO Core: 6.1.18
• Platform: espressif32@6.12.0
• Tool: tool-esptoolpy@2.40900.0
• Python used by PlatformIO: "~\Local\Programs\Python\Python311\python.exe"
• Host OS: Windows 10 (Git Bash + VSCode)
• Framework: Arduino
• Board: nodemcu-32s

How to Reproduce

1. Use a basic PlatformIO platformio.ini:

   platform = espressif32@6.12.0
   board = nodemcu-32s
   framework = arduino

2. Ensure intelhex is not installed in the Python environment used by PlatformIO

3. Run platformio run or call a build script

4. Observe this crash:

   File "...tool-esptoolpy\esptool\bin_image.py", line 16, in
   from intelhex import HexRecordError, IntelHex
   ModuleNotFoundError: No module named 'intelhex'

Expected Behavior

• If .hex functionality is unused, intelhex should not be required
• Builds should succeed without forcing intelhex installation

Actual Behavior

• Even .bin-only ESP32 builds fail due to an import in bin_image.py that is not guarded by a try-except

Suggested Fixes

1. Move the from intelhex import ... inside the function that needs it
2. Or wrap in a try-except ImportError block and emit a clear message if .hex usage is triggered
3. Or add intelhex to tool-esptoolpy's install-time requirements

Workaround
Manually install intelhex into the Python environment used by PlatformIO:

"~\Local\Programs\Python\Python311\python.exe" -m pip install intelhex

Impact
This silently breaks ESP32 builds for users after updating to espressif32@6.12.0, even for projects that don't need .hex support. The crash is non-obvious and unrelated to the user's code or libraries.

[rotorman]

I can confirm this to be an issue as listed above (tested building https://github.com/ExpressLRS/ExpressLRS/tree/master/src )

[valeros]

Hi there, can someone try pulling the latest tool-esptoolpy package and see if it works? For example via CLI:
pio pkg update -g -t tool-esptoolpy.

[rotorman]

That does not seem to solve the issue, at least not with currently latest tool-esptoolpy offered (2.40900.250804 (4.9.0)).

[valeros]

@rotorman So the error is the same? Could you try removing the tool-esptoolpy package manually? It should be somewhere here c:\Users\YOUR_USER\.platformio\packages\tool-esptoolpy or /home/YOUR_USER/.platformio/packages/tool-esptoolpy if you're on Linux. If possible, please also attach the logs of the first run after removing esptoolpy.

[rotorman]

That was an interesting tip - after deleting the folders and re-running the upload, I did NOT get the error anymore and flashing to ESP32 worked.

Tool Manager: Installing platformio/tool-esptoolpy @ ~2.40900.0
Unpacking  [####################################]  100%
Collecting cryptography~=45.0.3
  Downloading cryptography-45.0.5-cp311-abi3-win_amd64.whl.metadata (5.7 kB)
Collecting ecdsa~=0.19.1
  Downloading ecdsa-0.19.1-py2.py3-none-any.whl.metadata (29 kB)
Collecting bitstring~=4.3.1
  Downloading bitstring-4.3.1-py3-none-any.whl.metadata (5.3 kB)
Collecting reedsolo~=1.7.0
  Downloading reedsolo-1.7.0-py3-none-any.whl.metadata (23 kB)
Collecting intelhex~=2.3.0
  Using cached intelhex-2.3.0-py2.py3-none-any.whl.metadata (2.7 kB)
Collecting cffi>=1.14 (from cryptography~=45.0.3)
  Downloading cffi-1.17.1-cp311-cp311-win_amd64.whl.metadata (1.6 kB)
Collecting six>=1.9.0 (from ecdsa~=0.19.1)
  Downloading six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB)
Collecting bitarray<4.0,>=3.0.0 (from bitstring~=4.3.1)
  Downloading bitarray-3.6.0-cp311-cp311-win_amd64.whl.metadata (36 kB)
Collecting pycparser (from cffi>=1.14->cryptography~=45.0.3)
  Using cached pycparser-2.22-py3-none-any.whl.metadata (943 bytes)
Downloading cryptography-45.0.5-cp311-abi3-win_amd64.whl (3.4 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.4/3.4 MB 98.2 MB/s eta 0:00:00
Downloading ecdsa-0.19.1-py2.py3-none-any.whl (150 kB)
Downloading bitstring-4.3.1-py3-none-any.whl (71 kB)
Downloading reedsolo-1.7.0-py3-none-any.whl (32 kB)
Using cached intelhex-2.3.0-py2.py3-none-any.whl (50 kB)
Downloading bitarray-3.6.0-cp311-cp311-win_amd64.whl (144 kB)
Downloading cffi-1.17.1-cp311-cp311-win_amd64.whl (181 kB)
Downloading six-1.17.0-py2.py3-none-any.whl (11 kB)
Using cached pycparser-2.22-py3-none-any.whl (117 kB)
Installing collected packages: reedsolo, intelhex, bitarray, six, pycparser, bitstring, ecdsa, cffi, cryptography
Successfully installed bitarray-3.6.0 bitstring-4.3.1 cffi-1.17.1 cryptography-45.0.5 ecdsa-0.19.1 intelhex-2.3.0 pycparser-2.22 reedsolo-1.7.0 six-1.17.0                                                              

[notice] A new release of pip is available: 25.1.1 -> 25.2
[notice] To update, run: python.exe -m pip install --upgrade pip
Tool Manager: tool-esptoolpy@2.40900.250804 has been installed!
Verbose mode can be enabled via `-v, --verbose` option

build flags: ['-D CONFIG_TCPIP_LWIP=1', '-D BEARSSL_SSL_BASIC', '-D CONFIG_DISABLE_HAL_LOCKS=1', '-I ${PROJECTSRC_DIR}/hal', '-Wall -Iinclude', '-include target/Unified_ESP32_TX.h', '-D VTABLES_IN_FLASH=1', '-O2', '-DLATEST_COMMIT=52,56,55,97,52,50', '-DLATEST_VERSION=101,115,112,110,111,119', '-DTARGET_NAME=UNIFIED_ESP32_2400_TX']

Building for ESP32 Platform
CONFIGURATION: https://docs.platformio.org/page/boards/espressif32/esp32dev.html
PLATFORM: Espressif 32 (6.12.0) > Espressif ESP32 Dev Module
HARDWARE: ESP32 240MHz, 320KB RAM, 4MB Flash
DEBUG: Current (cmsis-dap) External (cmsis-dap, esp-bridge, esp-prog, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa)
PACKAGES:
 - framework-arduinoespressif32 @ 3.20017.241212+sha.dcc1105b
 - tool-esptoolpy @ 2.40900.250804 (4.9.0)
 - tool-mkfatfs @ 2.0.1
 - tool-mklittlefs @ 1.203.210628 (2.3)
 - tool-mkspiffs @ 2.230.0 (2.30)
 - toolchain-xtensa-esp32 @ 8.4.0+2021r2-patch5

esptool.py v4.2.1
Serial port COM13
Connecting......
Chip is ESP32-D0WDQ6 (revision 1)

Writing at 0x000d5e8d... (100 %)
Wrote 823312 bytes (531879 compressed) at 0x00010000 in 12.4 seconds (effective 529.1 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting via RTS pin...

As I can take it from the above, intelhex~=2.3.0 is now automatically installed.

[BlueAndi]

@rotorman So the error is the same? Could you try removing the tool-esptoolpy package manually? It should be somewhere here c:\Users\YOUR_USER\.platformio\packages\tool-esptoolpy or /home/YOUR_USER/.platformio/packages/tool-esptoolpy if you're on Linux. If possible, please also attach the logs of the first run after removing esptoolpy.

Removing the tool-esptoolpy was the solution for me as well.

[sonu27]

I had the same issue. Went back to 6.11

[rotorman]

Works fine now with v6.12 for me.

[vidplace7]

We are still experiencing this issue at the Meshtastic project, when using esptool inside an extra_script.

    # IntelHex workaround, remove after fixed upstream
    try:
        import intelhex
    except ImportError:
        env.Execute("$PYTHONEXE -m pip install intelhex")
    # /IntelHex workaround
    import esptool

^ This workaround is functional but... nasty

[valeros]

@vidplace7 Any hints on how to reproduce the issue? Do you have a failing CI pipeline or something I can take a look at?