• Toolchains
  • Developer

ESP-IDF and ~/.espressif: toolchains for every chip and every framework version

ESP-IDF installs a compiler per chip family, a Python environment per IDF version, and keeps every download archive. Where each is and what to clear.

5 min read

ESP-IDF itself is a Git checkout, usually in ~/esp/esp-idf. The tools it needs go elsewhere: ~/.espressif, or wherever IDF_TOOLS_PATH points. That folder holds a cross compiler for each chip family you target, debuggers, a Python environment per IDF version, and the archives every tool was installed from.

Measure it

du -sh ~/.espressif ~/esp 2>/dev/null
du -sh ~/.espressif/* 2>/dev/null | sort -h
du -sh ~/.espressif/tools/* 2>/dev/null | sort -h
FolderWhat it holds
toolsCompilers, debuggers and utilities, one folder per tool, version subfolders inside
python_envA Python environment per IDF version and Python version
distThe downloaded archives tools were installed from

What usually piles up

  • Old tool versions after upgrading IDF. A new IDF release often moves to a newer compiler, and the old one stays.
  • Python environments for IDF versions you no longer use.
  • The dist folder, which is pure installer archives.

Clearing it

Recent versions of the tools installer can remove tools the current IDF version does not use. Run it from your IDF checkout, with that version's environment active:

cd ~/esp/esp-idf
. ./export.sh
python tools/idf_tools.py uninstall --help

If your version has it, uninstall with --remove-archives clears unused tools and the dist archives. If it does not, the dist folder can be moved to the Trash by hand, and Python environments named for IDF versions you no longer have can go the same way.

PlatformIO keeps its own separate copy of these toolchains, covered in PlatformIO taking up space. For other cross compilers, see cross compilers taking up space.

Common questions

Where does ESP-IDF store its tools on a Mac?

In ~/.espressif, or the folder IDF_TOOLS_PATH points to. The framework itself is usually a separate Git checkout in ~/esp/esp-idf.

Can I delete the ~/.espressif/dist folder?

Yes. It holds the archives tools were installed from. The installed tools are in the tools folder and keep working.

How do I remove old ESP-IDF toolchains?

Recent versions support python tools/idf_tools.py uninstall from the IDF checkout, which removes tools that version does not use. Run it from each IDF version you keep.

Read next