# Tools

[中文]

## gdbgui Installation

The support for the `--enable-gdbgui` argument has been removed from the install scripts, and gdbgui cannot be installed this way anymore. Please use the `pipx` method from the gdbgui installation guide in order to set up this tool.

Depending on your operating system and Python version, you may need to consult the list of known issues.

For example, Python 3.13 is not supported on any operating systems at the moment.

The Windows operating system is not supported since gdbgui version 0.14. Because of the existence of other issues, you will need Python 3.10 with some specific versions of the dependencies. The last known working gdbgui and dependency versions can be installed with the following command:

    pipx install "gdbgui==0.13.2.0" "pygdbmi<=0.9.0.2" "python-socketio<5" "jinja2<3.1" "itsdangerous<2.1"

On Linux or macOS, you can use Python 3.11 or 3.12 and gdbgui version 0.15.2.0.

Please be aware that these recommendations may change over time. For an up-to-date list of issues, please refer to the official issue tracker.

We recommend to use `idf.py gdb` instead of `idf.py gdbgui`, or debug in Eclipse/Vscode if you encounter an issue with the installation.

## `idf.py efuse*` Commands Require Port

All commands with eFuse functionality now require a serial port to be specified. This was done to prevent accidental use of the wrong port, as these operations are irreversible.

For all `idf.py efuse*` commands, you now need to specify the serial port with the `--port` argument (or `ESPPORT` environment variable). If the port is not specified, the command will fail with an error message.

## Python 3.9 Deprecation

Python 3.9 is no longer supported. The minimum required Python version is now 3.10. Please upgrade your Python installation to version 3.10 or later. Alternatively, you can use the provided Docker images. For more information, see IDF Docker Image.

Refer to the official Python documentation for instructions on upgrading Python for your operating system.

For Linux users, it is recommended to upgrade to a newer version of your distribution that includes a supported Python version.

## Changes in Configuration Files Syntax

ESP-IDF v6 uses esp-idf-kconfig v3, which introduces several changes in the configuration (`Kconfig`) files. For the full list of changes, please refer to the esp-idf-kconfig migration guide from v2.x to v3.x.

## CMake version upgrade

The minimal supported CMake version has been upgraded to 3.22.1. In case you encounter build issues regarding this change, we recommend updating your operating system to a version that includes CMake 3.22 or newer.

If updating the OS is not possible, you can install a recommended CMake version using the following command: `./tools/idf_tools.py install cmake`.

This affects ESP-IDF users who use system-provided CMake and custom CMake.

## Unit-Test-App

The legacy unit-test-app has been moved out of ESP-IDF repository as it is no longer used by any ESP-IDF component for running tests. It is now available at The ESP Component Registry and a test app can be created using the `idf.py create-project-from-example` command:

    idf.py create-project-from-example espressif/unit-test-app:unit-test-app

## Catch

The header-only copy of Catch2 unit testing library previously located in tools/catch directory has been removed. To continue using Catch2 in your project, migrate to Catch2 3.x, available from The ESP Component Registry. For an example of migrating from Catch2 2.x to Catch2 3.x, see commit 79a2c15477dc327550ff46a64ee0f8b4679cc417.

## Dropped `idf.py size --legacy` option

The `--legacy` argument for `idf.py size` has been removed, as the legacy implementation is no longer supported. The `ESP_IDF_SIZE_LEGACY` environment variable also no longer has any effect. To continue using the legacy option, use ESP-IDF version 5.5 or lower. For ESP-IDF v6.0 and later, simply replace `idf.py size --legacy` with `idf.py size`. If you encounter esp-idf-size version problems, please run the install script to update to the correct version.

## Changed `idf.py size --format json` to `--format json2`

The `--format json` option has been replaced with `--format json2`. The `json2` format provides better structure with explicit `total`, `used`, and `free` fields for each memory region, and detailed breakdown in the `parts` section. To migrate, replace `idf.py size --format json` with `idf.py size --format json2`.

- Old format (json): Flat structure with direct memory type fields like `"dram_data": 9192, "iram_text": 43295`.

- New format (json2): Hierarchical structure with a `layout` array containing memory regions:

  >     {
  >         "version": "1.1",
  >         "layout": [
  >             {
  >                 "name": "DRAM",
  >                 "total": 180736,
  >                 "used": 11344,
  >                 "free": 169392,
  >                 "parts": {
  >                     ".data": {"size": 9192},
  >                     ".bss": {"size": 2152}
  >                 }
  >             }
  >         ]
  >     }

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.