This extension adds debugging capabilities for the
programming language to Visual Studio Code
and depends on the R package vscDebugger
For further R support in VS Code see vscode-R.
The debugger includes the following features:
- Run and debug R Code by launching a new R process or attaching to a running one.
- View scopes and variables of the currently selected stack frame.
For many variables it is also possible to assign a new value to the variable or individual entries/attributes in this view.
- Add watch expressions that are evaluated in the selected stack frame on each breakpoint/step.
- View and browse through the call stack when execution is paused.
- Set breakpoints and break on errors.
- Control the program flow using step, step in, step out, continue.
- Output generated by the program is printed to the debug console (filtering out text printed by the browser itself).
- The debugger adds a modified version of
str that also print a link to the file and line where the text was printed.
- The debug console allows the execution of arbitrary R code in the currently selected stack frame.
The latest version of the VS Code extension can be installed from the
After installing the extension, the R package can be installed using the command
If this does not work, you can find the source code and compiled binaries on the
The provided packages were built using the latest R release and might be incompatible with older R versions.
In these cases it is necessary to build the package from code.
If you want to install a development version, the VS Code extension can be installed from the .vsix-files found
To download the correct file, filter the commits by branch, select the latest commit,
and download the file
r-debugger.vsix under the caption "Artifacts".
To install the latest development version of the required R-package from GitHub, run
or install from the artifacts found
If your R path is neither in the Windows registry nor the
PATH environment variable, make sure to provide a valid path to the R executable in
Using the Debugger
- Press F5 and select
R Debugger as debugger. With the default launch configuration, the debugger will start a new R session.
- To run a file, focus the file in the editor and press F5 (or the continue button in the debug controls)
- Output will be printed to the debug console,
expressions entered into the debug console are evaluated in the currently active frame
- During debugging in the global workspace it is often necessary to click the dummy frame
in the callstack labelled 'Global Workspace' to see the variables in
- Start R in a terminal
- Start the debugger with launch configuration including
"name": "Attach to R process"
For a detailed explanation of possible launch config entries and other settings, see
Encoding issues on windows
Due to some changes in v0.5.0 concerning the communication between this extension and the R package
combined with the way non-utf-8 encodings are handled in R,
there might be some problems with this extension on Windows.
However, as of R-version 4.2.2, R can handle UTF-8 encoded communication on Windows much better.
To avoid these issues, it is recommended to update R to at least v4.2.2 and use the latest version of this extension and the related R package.
How it works
The debugger works as follows:
- An R process is started inside a child process
- The R package
vscDebugger is loaded.
- The Debugger starts and controls R programs by sending input to stdin of the child process
- After each step, function call etc., the debugger calls functions from the package
vscDebugger to get info about the stack/variables
The output of the R process is read and parsed as follows:
- Information sent by functions from
vscDebugger is encoded as json and sent via a TCP socket.
These lines are parsed by the VS Code extension and not shown to the user.
- Information printed by the
browser() function is parsed and used to update the source file/line highlighted inside VS Code.
These lines are also hidden from the user.
- Everything else is printed to the debug console
Debugging R Packages
Packages can now be debugged using
To do so, it is required to install
pkgload (part of
load_all will be masked by a modified version that automatically sets breakpoints
in the loaded package and attaches the modified versions of
To always load a package when launching a debug session, you can specify an array of paths in the launch config entry
This is done (for the currently opened package) in the example debug config
Packages with a more complicated installation that might not be compatible with
load_all can also be debugged.
For this to work, the proper source information must be retained during the installation of the package
attr(attr(FUNCTION_NAME, 'srcref'), 'srcfile') for some function from the package):
- The package must be installed from source code (not CRAN or
- The flag
--with-keep.source should be set
- Extensions containing C code might cause problems.
Sometimes it helps to install the package using
to compile the binaries and again with
to retain the source information.
The packages that are being debugged then need to be specified in the launch config as follows:
To overwrite the
message functions for an individual package,
they need to be explicitly assigned somewhere in the package:
print <- print
cat <- cat
message <- message
This assignment can be overwritten by the debugger with
.vsc.message, but has no effect when not using the debugger.
For troubleshooting info, see Troubleshooting
This package is still under development.
If you have problems, suggestions, bug fixes etc. feel free to open an
or submit a pull request.
Any feedback or support is appreciated!
Special thanks to
for providing the C code used in the R package, and
for his numerous contributions and feedback!