Debugging Unity in VS Code: Setup and Attaching the Debugger

Debug.Log gets you far, but at some point you need to pause the game on a line and look at every variable. Debugging Unity in VS Code works well once it’s set up, and the setup has changed over the years, so many old tutorials no longer apply. This guide covers the current way: Microsoft’s Unity extension, the right Unity package, attaching to the Editor, using breakpoints, and fixing the usual reasons the debugger won’t connect or breakpoints stay hollow.

What You Need

• A recent VS Code.
• The .NET SDK installed (the C# Dev Kit and C# extension use it for language features).
• Microsoft’s Unity extension for VS Code, which brings the debugger.
• The Visual Studio Editor package in your Unity project (com.unity.ide.visualstudio). Despite the name, it’s the package that supports VS Code too.

The old “Debugger for Unity” extension and the “Visual Studio Code Editor” package are deprecated. If you have them, remove them, as they conflict with the current setup.

Install the VS Code Extensions

1. Open the Extensions view in VS Code (Ctrl+Shift+X).
2. Search for Unity and install the one published by Microsoft. It also installs C# Dev Kit and C# as dependencies.
3. Sign in to C# Dev Kit if prompted. Its license terms are the same as Visual Studio Community for individuals and small teams.

These extensions give you IntelliSense, Unity message highlighting and the debugger. If IntelliSense isn’t working after this, the IntelliSense fix guide covers the common causes.

Set Up the Unity Side

1. In Unity, open Window > Package Manager. Check that Visual Studio Editor is installed and updated to the latest version. If Visual Studio Code Editor is installed, remove it.
2. Open Edit > Preferences > External Tools (Unity > Settings on macOS).
3. Set External Script Editor to Visual Studio Code. If it isn’t listed, choose Browse and pick the VS Code executable.
4. Click Regenerate project files.
5. Open a script from Unity by double-clicking it. VS Code should open the project folder.

Open the whole project folder in VS Code, not single files. The debugger and IntelliSense need the solution and project files Unity generates.

Attach to the Unity Editor

1. In VS Code, open the Run and Debug view (Ctrl+Shift+D).
2. If there’s no launch configuration, create one: click create a launch.json file and choose Unity, or add it manually as below.
3. Select Attach to Unity and press F5.

A minimal .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Unity",
      "type": "vstuc",
      "request": "attach"
    }
  ]
}

When you attach, Unity may ask to switch to Debug mode. Unity’s code optimization has two modes, shown by the bug icon in the bottom right of the Editor status bar: Release mode (faster, no debugging) and Debug mode (allows breakpoints). Choose to enable debugging for this session or for all projects. You can also switch with that status bar icon before attaching.

With several Unity Editors open, VS Code shows a list. Pick the right one.

Breakpoints, Stepping and Watches

Click in the gutter left of a line number to set a breakpoint (a red dot). Press Play in Unity. When the line runs, the Editor freezes and VS Code highlights the line.

• Variables panel: locals, this and fields.
• Watch panel: add expressions like transform.position or rb.linearVelocity.magnitude.
• Call Stack: how you got here. Click frames to inspect callers.
• F10 step over, F11 step into, Shift+F11 step out, F5 continue.
• Conditional breakpoints: right-click a breakpoint and add a condition like health <= 0. Essential inside Update, which runs every frame.
• Logpoints: right-click the gutter and choose Add Logpoint to print a message without editing code or recompiling.

While paused, the Unity Editor is frozen. Don’t panic if it looks unresponsive; continue in VS Code. The breakpoints and Debug.Log guide has more debugging strategies.

Debugging a Build

You can attach to a running player too:

1. In your build profile, tick Development Build and Script Debugging. Optionally tick Wait For Managed Debugger so the game pauses at startup until you attach.
2. Run the build.
3. In VS Code, start Attach to Unity and pick the player from the list instead of the Editor.

For Android, the device must be reachable over the network or via USB with ADB. This is the best way to chase bugs that only happen in builds.

Useful Tips

• Switch back to Release mode when you’re done. Debug mode makes scripts run slower, which can mislead you when profiling.
• Break on exceptions. In the Breakpoints panel, enable breaking on exceptions to stop exactly where an error is thrown.
• Domain reload. Breakpoints survive recompiles, but the debugger may detach after a domain reload. Re-attach if breakpoints stop hitting.
• Keep project files fresh. After adding packages or assembly definitions, Unity regenerates project files automatically; if VS Code seems confused, use Regenerate project files.

Troubleshooting

Breakpoint is a hollow circle and never hits

The debugger isn’t attached, Unity is in Release mode, or the code shown isn’t what Unity compiled. Attach, switch to Debug mode, and save the file.

“Attach to Unity” doesn’t find the Editor

Update the Visual Studio Editor package, remove the deprecated VS Code Editor package, and restart both Unity and VS Code. Firewalls can also block the debugger connection.

Configured debug type ‘vstuc’ is not supported

The Microsoft Unity extension isn’t installed or enabled. Install it and reload VS Code.

Debugger disconnects after editing a script

Domain reload restarted the scripting runtime. Attach again.

Editor freezes when I press Play

A breakpoint was hit in Awake or Start. Look at VS Code and continue.

FAQ