---
id: esp-idf-panic-decoder
version: "1.5.0"
license: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# esp-idf-panic-decoder — ESP-IDF panic decoder

License: permissive · Maintenance: active · Downloads: 475.0K/mo

## What it is and what it does

esp-idf-panic-decoder is a Python tool that decodes crash information from Espressif microcontrollers running ESP-IDF. It reads panic handler output—register values and raw stack memory—and acts as a GDB server, translating that low-level data into human-readable backtraces. This is particularly useful on embedded architectures where the target device cannot perform backtracing itself, allowing developers to debug crashes remotely by feeding panic dumps into GDB.

The package is part of the official ESP-IDF SDK and depends on pyelftools and pyparsing to parse ELF binaries and structured output. It runs on Python 3.7 through 3.13 across macOS, Windows, and POSIX systems, making it accessible in most embedded development environments.

Use it for:

- Debugging Espressif chip crashes by converting panic dumps into GDB-readable backtraces.
- Analyzing stack memory from production devices that logged panic output but cannot run a debugger locally.
- Automating crash analysis in CI/CD pipelines by parsing panic logs and generating structured debug information.
- Post-mortem debugging of embedded systems where live GDB connection is not available during the crash.
- Reverse-engineering the call stack from raw register and memory state captured at panic time.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Parses ESP-IDF panic handler output (registers and stack dumps) and presents the information to GDB as a server, enabling backtrace generation from raw stack dumps on architectures where on-target backtracing is not possible.

Yes. If you develop for Espressif microcontrollers and need to debug crashes from panic dumps, this is the standard tool. It has low install friction, active maintenance, permissive licensing, no known vulnerabilities, and is widely used in the embedded community. Install it if you work with ESP-IDF projects and encounter panic output you need to decode.

## Install

pip install esp-idf-panic-decoder
uv add esp-idf-panic-decoder
poetry add esp-idf-panic-decoder

## Installing esp-idf-panic-decoder

Before you install: Low install friction with only two lightweight runtime dependencies (pyelftools and pyparsing). Actively maintained with a recent release; repository is not archived and receives regular commits.

License in practice: Released under Apache License Version 2.0, a permissive open-source license that allows commercial use, modification, and redistribution with minimal restrictions—suitable for both proprietary and open-source projects.

Quickstart:

pip install esp-idf-panic-decoder

from esp_idf_panic_decoder import panic_decoder
# Parse panic output and connect to GDB
panic_decoder.main()

Requires GDB to be installed and available on the system; designed for use with Espressif ESP-IDF projects.

Verify before relying:

- Whether the package works with all ESP-IDF versions or has specific version constraints beyond Python 3.7+.
- Performance characteristics when processing very large stack dumps or multiple panic outputs in sequence.
- Availability of command-line interface documentation or examples beyond the description excerpt provided.
- Whether pyelftools and pyparsing have any known vulnerabilities or compatibility issues.

## Package facts

- License: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 475.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

esp-idf panic decoder, gdb backtrace from stack dump, espressif panic handler parser, embedded systems debugging, crash analysis embedded, gdb server for embedded, stack trace recovery, embedded-debugging, esp-idf, gdb-integration

[View on SkillFed](https://skillfed.io/packages/esp-idf-panic-decoder) · [View on PyPI](https://pypi.org/project/esp-idf-panic-decoder/)