Skip to content

# Debug via VS Code

You can use Visual Studio Code to debug a development app via `briefcase dev`, or a bundled app that is built via `briefcase build` and run via `briefcase run` - including mobile apps.

## Development

During development on your host system, you can configure Visual Studio Code to start Briefcase. The "Run" menu in VS Code has an "Open Configurations" option; if that option is enabled, select it, and modify the `configurations` key so that it contains an entry like the following:

    {
        ...
        "configurations": [
            ...
            {
                "name": "Briefcase: Dev",
                "type": "debugpy",
                "request": "launch",
                "module": "briefcase",
                "args": [
                    "dev",
                ],
                "justMyCode": false
            }
        ]
    }

If you need to specify other options to `briefcase dev`, you can specify them in the `args` value.

If "Open Configurations" isn't enabled, select "Add Configuration" instead, and then enter the following details:

- Select "Python Debugger" as the debugger
- Select "Module" as the debug configuration
- Enter `briefcase` as the name of the module to run.

This will give you a stub configuration that is mostly correct; edit it to match the example above. The configuration will be saved in a `.vscode/launch.json` file in your project.

To start a debug session, open the debug view in VS Code using the sidebar, select the "Briefcase: Dev" configuration from the list at the top of the sidebar, and select "Start Debugging" from the "Run" menu. This will run `briefcase dev` in a debug session; you can set breakpoints, use the data inspection, use the debug console REPL and all other debugging features of VS Code. For more details about the VS Code configurations in the `.vscode/launch.json` file, see the VS Code documentation.

## Bundled App

Experimental feature

This is currently an experimental feature that is only supported on Windows, macOS, iOS and Android.

To debug a bundled app, the app must be modified to include a bootstrap that will connect to the VS Code debugger. This is done by passing the `--debug debugpy` option to `briefcase build`:

    $ briefcase build --debug debugpy

To build a mobile app, include the platform name in the `build` command - for example:

    $ briefcase build iOS --debug debugpy

This will build your app in debug mode and add debugpy, and a package that automatically starts `debugpy` at the startup of your bundled app.

Then, select "Open Configurations" from the "Run" menu, and add a new debug configuration to your `.vscode/launch.json` file:

    {
        "version": "0.2.0",
        "configurations": [
            ...
            {
                "name": "Briefcase: Attach",
                "type": "debugpy",
                "request": "attach",
                "connect": {
                    "host": "localhost",
                    "port": 5678
                },
                "justMyCode": false
            }
        ]
    }

You can now start your app in debug mode:

    $ briefcase run --debug debugpy

To run a mobile app, include the platform name in the `run` command - for example:

    $ briefcase run iOS --debug debugpy

Running the app in debug mode will automatically start the `debugpy` debugger and listen for incoming connections. By default it will listen on `localhost` and port `5678`. The app will pause at the start of execution, waiting for the debugger to attach.

To attach the debugger, select the Debug sidebar, select the "Briefcase: Attach" configuration, and then select "Start Debugging" from the "Run" menu. The app will then resume, and the debugger will be enabled. You can then use any debugger features you require.

## Debugging quirks

The VS Code debugger has some notable behavior when used to debug a Briefcase app:

- The "Restart" debug control will not work. To restart the app, you need to disconnect the debugger, restart the app manually, running it with `briefcase run --debug debugpy`, and then re-connecting the debugger.
- `justMyCode` must be set to `false`. When setting it to `true`, or not defining it at all, breakpoints are missed on some platforms (e.g., Windows). The reason for this is currently unknown.
- `pathMappings` should not be set manually in the `launch.json`. The path mappings will be set by Briefcase programmatically and if setting it manually too the manual setting will overwrite settings by Briefcase.
- VS Code will not honor any breakpoint in code that is part of a file that is ignored by `.gitignore`.