languages/<id>.toml, [debugger] table), and the IDE starts that adapter when you debug a run configuration. Commands and shortcuts follow IntelliJ IDEA, so most of what you know from IDEA works the same way.
Start a debug session
Any run configuration with a debug adapter can be debugged:- Click the gutter run icon next to a
mainfunction or test and choose Debug. - Pick a configuration in the run widget on the toolbar and click the debug button.
- Use Run › Debug to debug the selected configuration, Run › Debug… to choose one, or Run › Debug Context Configuration to debug the program or test at the caret.
⌘5 / Alt+5) opens with one tab per session. It has two views:
- Threads & Variables: the threads, the stack frames of the selected thread, and the variables of the selected frame. Library frames are folded; use Show All Frames to expand them.
- Console: the program’s output, plus an input line that evaluates expressions in the selected frame. Browse earlier expressions with Browse Console History (
⌘⌥E/Ctrl+Alt+E).
Supported debuggers
A configuration can also use GDB 14 or newer (
gdb -i dap) for C and C++: choose GDB (C, C++) in its Debug adapter field. GDB is never installed by the IDE (apt install gdb, dnf install gdb, brew install gdb).
One-click installs live in Settings › Languages & Frameworks › Language Servers, which lists debuggers next to language servers. You can install, update or point the IDE at your own copy there.
Breakpoints
Click a line number to add or remove a line breakpoint, or use Toggle Line Breakpoint (⌘F8 / Ctrl+F8). In the gutter:
⌥-click (Alt-click) adds a temporary breakpoint, which is removed after it is hit once.⇧-click (Shift-click) adds a logging breakpoint that does not suspend the program, and opens its properties.- Middle-click enables or disables an existing breakpoint.
- Right-click a breakpoint to edit its properties.
Breakpoint properties
In the Breakpoints dialog the same options are available, plus Remove once hit, which makes the breakpoint temporary. Which of these work depends on the adapter: conditions, hit counts and log messages are DAP features that most, but not all, adapters support.
Other breakpoint kinds
Method breakpoints and field watchpoints need an adapter that supports DAP function and data breakpoints. Filters for debugpy, java-debug, js-debug and CodeLLDB are listed right away; other adapters’ filters appear after you have debugged with them once.
The Breakpoints dialog
View Breakpoints… (⌘⇧F8 / Ctrl+Shift+F8) lists every breakpoint in the project. From there you can enable, edit, remove and jump to breakpoints, toggle Mute breakpoints (skip all of them without removing them), and set exception filters. Remove All Breakpoints clears the list.
Breakpoints are saved per project and kept across restarts. A breakpoint the adapter could not place is shown as unverified.
Step through code
These commands are in the Run menu and on the Debug tool window toolbar.- Smart Step Into lets you pick which call on the current line to step into, when the line has several.
- The force variants ignore breakpoints on the way.
- Run to Cursor is also offered as an inline button on a line while the program is suspended (Show inlay Run to Cursor popup in the Debugger settings).
- Reset Frame returns to the start of the selected frame’s method, when the adapter supports it.
Inspect and change values
While the program is suspended:- The Variables view shows the variables of the selected frame. Right-click a value for Set Value… (
F2), Copy Value, Copy Name, Jump to Source (F4) and Add to Watches. - Watches appear at the top of the Variables view and are re-evaluated on every stop and frame change. Add one with Add to Watches; remove it with Remove Watch.
- Hovering a variable in the editor shows its value.
⌥-click (Alt-click) or Quick Evaluate Expression (⌘⌥F8/Ctrl+Alt+F8) evaluates the expression under the mouse or the selection. - Values of local variables are shown inline after the lines that use them.
- Evaluate Expression… (
⌥F8/Alt+F8) opens a dialog that evaluates any expression in the selected frame, keeps a history, and can add the expression to watches.
Attach to a running process
Run › Attach to Process… (⌥⇧F5 / Ctrl+Alt+F5) lists your processes that a debugger can attach to, grouped by debugger:
Type to filter by name, PID or command line.
Remote debug configurations
To debug a process started elsewhere (another machine, a container), add one of these configurations in Run › Edit Configurations…. They only support Debug; they do not start a process.
Each form has Host and Port fields and shows the command to start the remote side with. Local root and Remote root map source paths when the remote code lives in a different folder.
Language-specific features
- Java HotSwap: Run › Debugging Actions › Reload Changed Classes compiles your changes and reloads the changed classes into the running Java debug session. Active frames keep running the old code until they return. When JDT LS finishes a build after a save, the IDE offers the reload.
- Maven and Gradle: debugging a Maven or Gradle configuration starts the JVM with a JDWP agent and attaches java-debug to it.
- Dart / Flutter: Hot Reload and Hot Restart are available while a Dart session is running.
- PHP: if the PHP interpreter does not load Xdebug, breakpoints are skipped; the IDE warns about this when the session starts.
- Python: Settings › Build, Execution, Deployment › Python Debugger has Attach to subprocess automatically while debugging and Gevent compatible.
Settings
Settings › Build, Execution, Deployment › Debugger:- Show debug window on breakpoint hit, Focus application on breakpoint, Hide debug window on process termination.
- Breakpoints: Allow placing breakpoints in any file, Show inlay Run to Cursor popup.
- Data Views: Show values inline, Sort values alphabetically, Show value tooltip on mouse hover, Show value tooltip on code selection, Value tooltip delay (ms).
- Stepping: Do not step into library scripts (Python: only your code; JavaScript: skips
node_modulesand Node.js internals).
Shortcuts
All shortcuts are from the default keymap and can be changed in Keymap settings.