Skip to content

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

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions