What is the difference between idf.py clean and idf.py fullclean, and when do you need the second?

clean deletes the build output (object files, binaries) but keeps CMake's configuration, so the next build recompiles everything without reconfiguring. fullclean deletes the whole build/ directory including the CMake configuration, so the next build starts from nothing.

A build has two layers. CMake first configures the project: it finds the compiler, resolves the components and writes the Ninja build files into build/. Ninja then compiles using those files. The two clean commands throw away different amounts:

Use clean when you just want a fresh compile. Reach for fullclean when the configuration itself is stale: you switched ESP-IDF versions, moved the project, added or removed components, or the build fails with errors that make no sense for the code. Neither deletes your source code or the project's sdkconfig file in the project folder; fullclean only touches what lives inside build/.

Go deeper:

• ESP-IDF — idf.py clean and fullclean — the official wording for both commands.