Configure VS Code for ESP-IDF ( OS X / Linux )

Build Output
Build Output
Serial Monitor
Serial Monitor
Debug Panes
Debug Panes
Debug with Serial Monitor
Debug with Serial Monitor
OpenOCD Server
OpenOCD Server


esp tools path

New Project

  • Copy an ESP-IDF project
  • Add the vscode.esp folder to the root of the project
  • Rename vscode.esp to .vscode
  • To rename the project:
  • Any folder with sources to build must contain a CMakeLists.txt file
  • Update c_cpp_properties.json to include your header locations (please see file notes below)


  • Install OpenOCD to ~/esp/ (elsewhere is ok just mind the .json paths)
    • OS X Specific:
      • Do not install FTDI VCP driver or hack kexts
      • Install libusb: brew install libusb
      • Unload Apple FTDI Driver: sudo kextunload -verbose -bundle-id -personalities-only
      • More Info about low-level usb port access for jtag
  • Edit launch.json and verify paths and serial port
  • Edit tasks.json and make sure paths of the “OpenOCD” task are correct
    • (i.e. ~/esp/openocd-esp32/bin/openocd and ~/esp/openocd-esp32/share/openocd/scripts)
  • Start OpenOCD server before debugging (F12 - Tasks: Run Task: OpenOCD)


  • Include this file in your main file for ESP-IDF menuconfig definitons
// esp-idf definitions
#include "sdkconfig.h"

Hotkeys and Tasks

  • Press a key and run a task, or use the command menu to run a task by name.
F4 Config
F5 Debug
F6 Clean
F7 Build
F8 Flash
F9 Flash Monitor
F10 Monitor
F12 OpenOCD


  • This file tells VS Code's IntelliSense engine where to find headers.
  • Paths must be specified non-recursively like ${env:IDF_PATH}/components/freertos/include
  • In order to make this easier, VS Code has a contextual menu that appears as a lightbulb above missing files. The cursor must be within the squiggle for the lightbulb to appear.
  • Click the lightbulb, select the appropriate header path, and it will be appended to the includePath variable automatically.
    • Note: Although recursive paths may be specified like ${env:IDF_PATH}/components/**, the ESP-IDF contains redundant headers in various locations. Unfortunately this confuses IntelliSense, and it falls out of sync with the ESP-IDF toolchain. However, this recursion may work for other folder structures with unique filenames.


  • Shell script to generate flash folder containing .bin files and script
  • Make sure serial port is correct



  • These custom keybindings should be added to the local keybindings.json file of your VS Code installation.
  • Preferences → Keyboard Shortcuts → { } file tab bar button



  • Debugger setup script



  • Configuration file for the Monitor screen session



  • Configuration file for the OpenOCD server screen session



  • These tasks configure VS Code to work like an IDE for the ESP-IDF
  • Make sure paths and serial port in “OpenOCD” task are correct
    • i.e. ~/esp/openocd-esp32/bin/openocd and ~/esp/openocd-esp32/share/openocd/scripts


  • code/vscode.txt
  • Last modified: 02/06/2020
  • (external edit)