---
id: esp-idf-diag
version: "0.2.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# esp-idf-diag — Diagnostic tool for ESP-IDF

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

## What it is and what it does

esp-idf-diag is a command-line diagnostic tool for the Espressif IoT Development Framework. It gathers information about the ESP-IDF environment, system configuration, and the current ESP-IDF project, organizing the collected data into a report directory. The tool is designed to help developers troubleshoot problems by automating the collection of relevant diagnostic information.

Data collection is managed through YAML-based recipes that specify which commands to run and capture. The tool includes automatic redaction of sensitive information (passwords, tokens in URLs) guided by a configurable purge file in YAML format. Once a report is generated, it can be compressed into a zip archive for easy sharing with maintainers or in GitHub issues. The tool supports Python 3.7 through 3.13 and runs on macOS, Windows, and POSIX systems.

Use it for:

- Generate a diagnostic report when encountering build or runtime issues in an ESP-IDF project to share with the Espressif team.
- Collect system and environment information automatically before filing a bug report on GitHub.
- Create a redacted snapshot of your ESP-IDF setup for troubleshooting without exposing credentials or private paths.
- Archive diagnostic data from multiple development machines to compare configurations and identify environment-specific problems.

## Worth the install?

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

Collects ESP-IDF environment, system, and project information into a diagnostic report directory, with optional redaction of sensitive data and zip archive export for sharing.

Yes. This is a lightweight, actively maintained diagnostic utility with no known vulnerabilities and permissive licensing. Install it if you develop with ESP-IDF and want to streamline bug reporting or troubleshooting. The low install friction and minimal dependencies make it a practical addition to any ESP-IDF workflow.

## Install

pip install esp-idf-diag
uv add esp-idf-diag
poetry add esp-idf-diag

## Installing esp-idf-diag

Before you install: Low install friction with a pure-Python wheel and only two runtime dependencies (PyYAML and rich). Active maintenance with a recent release and no known vulnerabilities.

License in practice: Licensed under Apache Software License (permissive), which allows commercial and private use with minimal restrictions.

Quickstart:

$ pip install esp-idf-diag
$ esp-idf-diag create
$ esp-idf-diag zip diag-UUID

Requires an activated ESP-IDF environment to run the create command.

Verify before relying:

- Whether custom recipe YAML files can extend the default data collection beyond what is built-in.
- Performance characteristics when collecting diagnostics from large or complex ESP-IDF projects.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 410.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

esp-idf diagnostic tool, esp-idf environment report, embedded systems troubleshooting, esp-idf bug report generator, system diagnostics for espressif, esp-idf debug information collector, esp-idf, embedded-systems, diagnostics

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