Registry / devops / esp-idf-panic-decoder

esp-idf-panic-decoder

library1.5.0pypypi✓ verified 85d ago

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.

devops observability

pip install esp-idf-panic-decoder

github ↗package ↗

INSTALL

IMPORT

SIG · ESP-IDF-PANIC-DECO

esp-idf-panic-decoder

devopspythonv1.5.0

Install

1.9s avg

Import

206ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.218s · 20.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.9s · import 0.194s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

esp_idf_panic_decoder

✓ import esp_idf_panic_decoder

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

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)

espidf_panic_decoder --version

Debug

Known issues

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

affects: >=1.5.0

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

affects: 1.4.0 - 1.4.2

gotchaThe 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').

affects: all

Errors

Common errors & fixes

ImportError: No module named 'esp_idf_panic_decoder'

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

ValueError: Could not find PC address in ELF file

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.

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

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

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

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()'.

Upgrade

Version history

1.5.0latest on PyPI · released Apr 13, 2026

Audit

Dependencies

pyparsingrequiredRequired for parsing panic output. Added explicitly in v1.5.0.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/espressif/esp-idf-panic-decoder ↗

packagehttps://pypi.org/project/esp-idf-panic-decoder/ ↗