How to Add OpenOCD Debugging to Arduino IDE

OpenOCD is a separate tool that Arduino IDE doesn't include by default

OpenOCD (Open On-Chip Debugger) is debugging software that lets you pause your Arduino code mid-run, watch variables change, and step through one line at a time. Arduino IDE comes with a basic uploader but not a debugger. Adding OpenOCD means installing it on your computer separately, then telling Arduino IDE where to find it.

This is different from uploading code. Uploading sends your program to the board and runs it. Debugging lets you inspect what the program is actually doing while it runs. Most Arduino boards support one or the other, not both — check your board's documentation first, because some cheaper boards cannot debug at all.

Key Takeaways

OpenOCD must be installed on your computer as a separate program before Arduino IDE can use it.
Your Arduino board must have a compatible debugger chip (usually CMSIS-DAP, ST-Link, or J-Link) — not all boards have one.
You configure the connection in Arduino IDE under Tools menu, not by editing files.
The first time you debug, you may need to install a USB driver for your debugger chip so your computer recognizes it.

Check whether your board actually supports debugging

Before installing anything, verify that your specific Arduino board can debug. Look at the board's product page or manual and search for "debugger" or "CMSIS-DAP". Boards like the Arduino Due, Arduino Zero, Arduino MKR series, and Arduino Nano 33 IoT have debugging hardware built in. Older boards like the Uno and Mega do not.

If your board has no debugger chip, you cannot use OpenOCD with it, no matter what you install. You would need an external debugger like a J-Link or ST-Link probe, which costs extra money and requires its own setup.

Install OpenOCD on Windows, Mac, or Linux

On Windows: read the OpenOCD installer from openocd.org/read. Run the .exe file and follow the setup wizard. Choose a folder you can remember — the default is usually fine. When asked about adding to PATH, say yes. Restart your computer after installation finishes.

On Mac: Use Homebrew if you have it installed. Open Terminal and type brew install open-ocd. If you do not have Homebrew, go to openocd.org/read and read the Mac binary, then follow the included instructions. Mac installation is usually faster than Windows.

On Linux: Most distributions have OpenOCD in their package manager. On Ubuntu or Debian, open Terminal and type sudo apt-get install openocd. On Fedora, type sudo dnf install openocd. You may need to add your user to the dialout group so you can access the USB port — ask in the Arduino forums if you hit a permission error.

Install the Arduino IDE debugging extension

Arduino IDE version 2.0 and later has built-in debugging support. If you are still using Arduino IDE 1.8, you need to install the Debugger extension first. Go to the Sketch menu, select Include Library, then Manage Libraries. Search for "Arduino Debugger" and install the version by Arduino.

If you are using IDE 2.0 or later, you already have debugging built in — no extra library needed. Check your version number in the Help menu if you are not sure which one you have.

Connect your board and configure the debugger in Arduino IDE

Plug your Arduino board into your computer with a USB cable. Open Arduino IDE and go to Tools menu. Look for an option called "Debugger" or "Debug Protocol" — the exact name depends on your IDE version and board type. Select "OpenOCD" from the dropdown.

Next, still in the Tools menu, find "Board" and make sure your exact board model is selected. Then find "Port" and select the USB port your board is connected to. On Windows it shows as COM3 or COM4. On Mac and Linux it shows as /dev/ttyUSB0 or similar. If you do not see a port, your board's USB driver is not installed — see the troubleshooting section below.

Install the USB driver for your board's debugger chip

Your computer needs to recognize the debugger chip on your board as a USB device. Most modern boards handle this automatically, but some require a manual driver install. If Arduino IDE shows no port in the Tools menu, or shows a port but debugging fails with a "device not found" error, you need the driver.

Go to your board manufacturer's support page and search for "USB driver" or "debugger driver". For Arduino boards, this is usually on arduino.cc/en/Guide. read the driver for your operating system and follow the included instructions. Windows often requires you to restart after driver installation. After restart, plug your board back in and check the Tools menu again.

Test the debugger with a straightforward sketch

Write or open a very straightforward sketch — something like a loop that increments a counter. Set a breakpoint by clicking the line number in the editor where you want the code to pause. The line number will turn red or show a dot. Then go to the Sketch menu and select "Start Debugging" or click the debug button (usually a play button with a bug icon).

The code should run until it hits your breakpoint, then pause. You should see a Variables panel showing the current value of each variable. If this works, your OpenOCD setup is complete. If the debugger does not start, check the error message in the console at the bottom of the IDE — it usually tells you what went wrong.

Frequently Asked Questions

What if Arduino IDE says "OpenOCD not found"?

OpenOCD is installed but Arduino IDE cannot locate it. On Windows, make sure you restarted your computer after installation and that you chose "add to PATH" during setup. On Mac and Linux, open Terminal and type which openocd to confirm it is installed. If the command returns nothing, reinstall OpenOCD using the method for your operating system.

Can I debug an Arduino Uno?

Not with OpenOCD alone. The Uno has no debugger chip. You would need to buy an external debugger probe like a J-Link or ST-Link and connect it to the Uno's ICSP pins, then configure OpenOCD to use that probe instead. This is more complex and costs extra.

Why does debugging say "device not found" even though the board is plugged in?

The USB driver for your debugger chip is not installed or not recognized. Go to your board's support page, read the correct driver for your operating system, and install it. Restart your computer and plug the board back in. Check the Tools menu again to see if a port appears.

Does debugging slow down my code?

Yes, slightly. When a breakpoint is set, your code runs slower because the debugger is watching it. Remove breakpoints you are not using, and disable the debugger entirely when you need full speed. Debugging is for finding bugs, not for running your final program.

What is the difference between OpenOCD and the Arduino debugger?

OpenOCD is the underlying tool that does the actual debugging work. The Arduino debugger is the interface in Arduino IDE that talks to OpenOCD. You install OpenOCD on your computer, and Arduino IDE uses it automatically once it is configured. You do not interact with OpenOCD directly.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.