Guides › Setup · Windows

Fix "idf.py is not recognized" on Windows

You installed ESP-IDF, opened a terminal, typed idf.py build, and Windows answers that idf.py is not recognized. ESP-IDF is installed; this terminal just does not know about it yet.

ESP-IDF 5.x and 6.x · Windows 10 and 11 · updated 27 October 2026

The full message usually looks like this in PowerShell:

idf.py : The term 'idf.py' is not recognized as the name of a cmdlet, function,
script file, or operable program.

or like this in Command Prompt:

'idf.py' is not recognized as an internal or external command,
operable program or batch file.

Why it happens

ESP-IDF does not add itself to the global PATH. Its tools (Python environment, CMake, Ninja, the compilers and idf.py) are put on the PATH only in a terminal where the ESP-IDF environment was exported. A new terminal, a VS Code terminal or a terminal opened before the installation finished does not have it.

Fix 1: open the ESP-IDF terminal the installer created

The ESP-IDF installer adds Start menu shortcuts such as ESP-IDF PowerShell and ESP-IDF CMD (with the version in the name). They open a terminal with the environment already exported. Go to your project folder there and run idf.py build. If this works, ESP-IDF is fine and only your usual terminal needs one of the fixes below.

Fix 2: export the environment in the terminal you use

Run the export script from the ESP-IDF folder, in the same terminal, before idf.py. The script depends on the shell:

Running export.bat inside PowerShell is the most common cause: the batch file runs in a child cmd process, its PATH changes are lost when it exits, and PowerShell still cannot find idf.py. In PowerShell always use export.ps1.

If PowerShell refuses with "running scripts is disabled on this system", allow local scripts for your user once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Fix 3: in VS Code, use the ESP-IDF terminal

With the official ESP-IDF extension, open the Command Palette (Ctrl+Shift+P) and run ESP-IDF: Open ESP-IDF Terminal. That terminal gets the environment of the ESP-IDF version the extension is configured for. A plain Terminal › New Terminal does not.

Fix 4: remove environment variables you set by hand

If you once added IDF_PATH, an ESP-IDF tools folder or a Python folder to the Windows environment variables yourself, remove them (Settings › System › About › Advanced system settings › Environment Variables). They often point to an older ESP-IDF or another Python and break the export script of the new one. Then open a new terminal and use fix 1 or 2.

Check that it worked

idf.py --version

It should print the ESP-IDF version, for example ESP-IDF v6.1. If it prints a different version than you expected, an old IDF_PATH is still set: see fix 4.