ESP-IDF Panic Decoder

1.5.0 verified Fri May 01 auth: no python

A Python tool to decode ESP-IDF panic backtraces and crash output. It translates program counter addresses to source file names, line numbers, and function names using ELF debug symbols. Current version is 1.5.0, released April 2026, with regular updates aligned with ESP-IDF release cycles.

pip install esp-idf-panic-decoder

Common errors

error ImportError: No module named 'esp_idf_panic_decoder' ↓

cause The package is installed under a different name or not installed.

fix

Install using 'pip install esp-idf-panic-decoder'. The import name is 'esp_idf_panic_decoder' (with underscores).

error ValueError: Could not find PC address in ELF file ↓

cause The ELF file does not contain the given address or is from a different build.

fix

Verify that the ELF file matches the firmware that generated the panic output. Use 'esptool.py elf2image' to check.

error esp_idf_panic_decoder.decode_crash() got an unexpected keyword argument 'target' ↓

cause In v1.5.0, the 'target' parameter was removed. The function now expects only panic_output and elf_path.

fix

Remove the 'target' argument. Update code to not pass 'target'.

error AttributeError: module 'esp_idf_panic_decoder' has no attribute 'decode_crash' ↓

cause The function may have been renamed in an older version or import path is wrong.

fix

Use 'from esp_idf_panic_decoder import decode_crash' or 'import esp_idf_panic_decoder; esp_idf_panic_decoder.decode_crash()'.

Warnings

breaking v1.5.0 removed target-specific register mapping and now uses a generic register set. If you relied on target-specific register names, your output may differ. ↓

fix Update any code that depends on target-specific register names. Use the generic register set provided.

deprecated In v1.4.0, batch request and addr2line extraction changed the output format. Some fields may have been renamed or removed. ↓

fix Check your parsing of decoded output if upgrading from <1.4.0.

gotcha The ELF file must contain debug symbols (not stripped) and must match the exact build that created the panic output. ↓

fix Ensure your firmware build includes debug symbols (e.g., build type 'DEBUG' not 'RELEASE').

Imports

esp_idf_panic_decoder
```
import esp_idf_panic_decoder
```
The library exports a module-level function `decode_crash` and CLI entry point.

Quickstart

Basic usage: decode panic output using an ELF file.

import esp_idf_panic_decoder
from esp_idf_panic_decoder import decode_crash

# Path to your ELF file (with debug symbols)
elf_path = '/path/to/firmware.elf'

# Example panic output (from serial console)
panic_output = """0x400d1234: do_crash at /build/main.c:123
0x400d5678: app_main at /build/main.c:45
"""

decoded = decode_crash(panic_output, elf_path)
print(decoded)