How to set a breakpoint in VS Code on Mac: steps for macOS and 2026

What a breakpoint does in VS Code

A breakpoint tells the debugger to pause your program on one line. When the program reaches that line, it stops before running it. You can then read variable values, check the call stack, and step through the code one line at a time.

Breakpoints only work in debug mode. If you start the program without debugging, VS Code ignores every breakpoint you set. Press F5 to run in debug mode after you place them.

Set a breakpoint by clicking the editor margin

The editor margin is the narrow strip to the left of the line numbers. Click it on the line where you want to pause. A solid red circle appears. That circle is an enabled breakpoint, and it stays until you remove it.

Click the red circle again to remove the breakpoint. The line goes back to normal, and the debugger no longer stops there. Nothing else in your file changes.

Pick a line that runs code

Not every line can hold a breakpoint. Comments and blank lines cannot. Many declarations cannot either. Choose a line that does real work, such as an assignment, a loop, an if statement, or a function call.

• Good: a line that assigns or changes a value.
• Good: the first line inside a function you want to inspect.
• Poor: a comment, a blank line, or a line that holds only a closing brace.
• Always check the dot after you click. A hollow gray circle means the debugger could not register it.

A hollow gray circle usually means the line has no executable code, or the debugger does not support that file. Move the breakpoint to a nearby line that runs code, then check the dot again.

Use F9 when clicking is awkward

Click into the line you want, then press F9. The breakpoint toggles on that line. Press F9 again to remove it. This beats aiming at a thin strip in a long file, or when a trackpad makes small clicks hard.

The shortcuts assume a standard US keyboard layout. If you use another layout, some keys sit in a different place. To find a missing shortcut, open Preferences: Open Default Keyboard Shortcuts (JSON) from the Command Palette.

Why F9 does nothing on a Mac

This is the most common snag. On a Mac keyboard, F9 is a function key. macOS can send the top row to system features instead of to apps like VS Code. So F9 can do nothing at all.

Apple controls this with a setting. Open System Settings, then go to Keyboard, Keyboard Shortcuts, and Function Keys. Turn on Use F1, F2, etc. keys as standard function keys. Apple describes this for macOS Ventura or later.

Breakpoint types and icons

VS Code uses several breakpoint types. Each one has its own shape in the editor and in the BREAKPOINTS list. Knowing the shapes tells you what kind of breakpoint you are looking at.

Filled red means enabled. Filled gray means disabled. Hollow gray means the debugger could not register the breakpoint. Those three states matter more than the shape when something stops working.

Conditional breakpoints and logpoints

A conditional breakpoint pauses only when an expression is true. Use one when a loop runs many times and you care about one pass. Right-click the margin, choose Add Conditional Breakpoint, and type the expression.

Say a loop goes through every order in a list, and one order has the wrong total. Set a conditional breakpoint on the total line. Use a condition that matches only that order's ID. The program then pauses on that one pass and nowhere else.

Condition syntax follows your language and your debugger. A Python condition is ordinary Python. A JavaScript condition is ordinary JavaScript. Test the expression on a simple value first, because a typo can stop the breakpoint from firing.

A logpoint does not pause. It prints a message each time the line runs, so the program keeps moving. Add one from the margin menu, or run Debug: Add Logpoint from the Command Palette. Logpoints only work if your debugger supports them.

A triggered breakpoint waits for another breakpoint to be hit first. Use it when a bug shows up late in a sequence, and you want to skip the early steps.

Function breakpoints and the BREAKPOINTS list

A function breakpoint pauses when a named function runs. You do not need to open the file that holds it. Open the Run and Debug view with ⇧⌘D, then click the plus sign in the BREAKPOINTS section and type the function name.

The BREAKPOINTS section lists every breakpoint in your project. Click the pencil icon to edit one. That is the same Edit Breakpoint action you get from the margin menu, so you can add a condition after the fact.

A long list gets hard to scan. Set debug.breakpointsView.presentation to tree to group breakpoints by file. Set debug.showBreakpointsInOverviewRuler to show breakpoints on the scrollbar while you scroll.

Start the debugger and watch it stop

Press F5 to start. If VS Code asks which debugger to use, choose the one that matches your language. VS Code creates a launch.json file when your app needs a specific entry point, arguments, or environment variables.

When the program reaches an enabled breakpoint, it pauses. Check the variables while it is stopped. Press F5 to continue to the next breakpoint. Press F11 to step into the function call on the paused line.

Open the Debug Console with ⇧⌘Y to read program output while it is paused. You can also type an expression there to test a value before you change any code.

Mistakes people make with breakpoints on a Mac

• Clicking a comment or a blank line. The dot turns hollow gray and never stops.
• Pressing a plain run command instead of starting the debugger. Breakpoints are skipped.
• Assuming F9 works without checking the function key setting first.
• Leaving an old condition on a breakpoint. The stop you want never happens.
• Expecting a logpoint to pause. It only prints a message.
• Debugging a copy of the file in another folder. Check which file path the debugger uses.

The last mistake is common in projects with several folders. Open the file from the folder the debugger runs, then set the breakpoint there. Otherwise the dot looks right, and the code still never pauses.

When a VS Code breakpoint does not hit

The official debugging docs do not include a troubleshooting section for breakpoints that never trigger. Forum posts and GitHub issues offer fixes. Microsoft has not verified them, so treat them as checks to try, not guarantees.

1. Confirm the dot is filled red, not gray or hollow.
2. Confirm you started with F5 and not a plain run command.
3. Check that the program path in launch.json points at the file you edit.
4. For compiled or transpiled code, rebuild and check source maps or outFiles.
5. Restart VS Code, then start the session again.

The first two checks take almost no time, so start there. Move down the list only if the breakpoint still stays silent.

Breakpoints on the web and in remote setups

VS Code for the Web has no debugger and no terminal. You cannot set a breakpoint that stops code there. Use the desktop app on your Mac for debugging.

If your code runs somewhere else, the VS Code docs list GitHub Codespaces and a remote tunnel as options for running, building, or debugging. Check the docs for the setup steps before you connect.

What changed in VS Code 1.145

VS Code 1.145 was released on November 4, 2026. The current update on the download page is 1.145.2. The release notes list no changes to the Run and Debug view, breakpoints, or the debugger.

Version 1.110 came out on March 4, 2026. It renamed the Event Listener Breakpoints view to Browser Options. If you debug browser code, that is the name you will see. It also added an Emulate a focused page option.

Keys and next steps

Once breakpoints feel natural, learn the step keys. The keybindings reference lists F9, F5, and F11, but it leaves out some stepping keys. Run Preferences: Open Default Keyboard Shortcuts (JSON) from the Command Palette to see the full list.

To run the file you are debugging, read How to run a Python file in VS Code on Mac. To find the debugger you need, see How to install an extension in VS Code on Mac.

For the Command Palette steps used above, see How to use the command palette in VS Code on Mac.