Extension Configuration

Workbench

Global extensions directory

The default configuration allows users to manage their own extensions. Alternatively, you can configure your environment to use a global extensions directory containing pre-installed extensions for your users. To configure a global extensions directory, pass the --extensions-dir argument to the rstudio-server configure-vs-code command when first configuring VS Code sessions or add it as an argument to vscode.conf. For example, to use a global extensions directory at /opt/code-server/extensions:

# likely need root privilege to install to /opt
sudo rstudio-server configure-vs-code --extensions-dir=/opt/code-server/extensions

This will overwrite the existing configuration with the default configuration. All arguments provided to the command will be added to the args entry in vscode.conf.

Once the configuration file is modified, you’ll need to restart the Posit Workbench service for it to detect changes.

Pre-Configuring VS Code extensions

Default configuration

Posit Workbench includes a configuration file vscode.extensions.conf which contains a list of extensions that administrators can modify. These extensions will be installed for each user when they launch their first VS Code Session. The file contains the following extensions by default:

quarto.quarto
posit.shiny
posit.publisher
Note

Extensions are only installed at session launch when a global extensions directory has not been configured. If you are using a global extensions directory, continue reading to learn how to pre-install extensions.

Admin configuration

Administrators can configure a list of extensions that will be installed for all users by creating a vscode.extensions.conf file. The file should contain a list of extensions with each extension on its own line. If the extension is to be installed from Open VSX, the line should include the full extension ID, including the publisher. For example, to install the latest version of the Quarto extension and version 2.6.1 of the R extension from Open VSX, include the following lines in vscode.extensions.conf:

quarto.quarto
REditorSupport.r@2.6.1

Alternatively, you can include paths to local extension files (.vsix):

/opt/code-server/company-extensions/company-extension-1.0.1.vsix
Note

These extension files must exist on the node where the session is launched, which may differ from where Posit Workbench is installed in Kubernetes and Slurm environments.

Each line of the file is passed directly to code-server’s install extension command allowing any argument or format accepted by this command to be included. To test out your command, you can run the following (omitting --extensions-dir if not using a global extensions directory):

code-server --extensions-dir=/opt/code-server/extensions --install-extension <test-line>

Installation

If configured with a global extensions directory, run rstudio-server install-vs-code-ext to install the extensions from vscode.extensions.conf.

If users are managing their own extensions, Posit Workbench will install the extension list when a user launches a VS Code session. Depending on the network speed and number of extensions, this could cause a noticeable increase in session load time the first time a user starts a VS Code session.

Extensions being installed from Open VSX will not be re-installed unless they are passed the --force argument in vscode.extensions.conf. However, extensions installed from a local copy will be re-installed each time the installation is attempted. If installing a significant number of extensions this way, we recommend configuring your environment to use a global extension directory to prevent increased session start times.

Databricks

If your team makes use of Databricks, the Databricks extension for VS Code allows you to remotely interact with the Databricks platform. This VS Code extension can make use of Databricks auth-passthrough if it is available and enabled for your Workbench instance.

Manual installation

If you have configured a global extensions directory, you can manually install extensions for your users.

Manually installing extensions

When VS Code sessions are configured with a global extensions directory, users without write access to this directory cannot install extensions, and the extensions marketplace will be disabled. Otherwise, users can manage their own extensions, and installs must be performed on a per-user basis by the user. There are three ways in which extensions can be installed:

  1. Install the extension from Open VSX using PWB Code Server. This can be done from within a VS Code session via the UI or via the command line with the following command:

    code-server --extensions-dir <extensions directory> --install-extension <extension publisher>.<extension name>

    For example, when using a global extensions directory at /opt/code-server/extensions, run the following command to install the Python extension:

    /usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server --extensions-dir=/opt/code-server/extensions --install-extension ms-python.python

  2. Download an extension in VSIX format from an online marketplace and install it using the --install-extension argument like the example above, passing the VSIX file path as the extension name. If the latest version of the extension is incompatible with the version of code-server, the extension will fail to install. In this case, explicitly set the version if the extension to a compatible version.

    For example, when code-server is installed at the default location, and you are using an extensions directory at /opt/code-server/extensions, run the following command to install an extension file named my-extension.vsix:

    /usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server --extensions-dir=/opt/code-server/extensions --install-extension ./my-extension.vsix
Note

It is against VS Code’s Terms of Service to use the official Marketplace extensions with third-party tools like PWB Code Server. Posit strongly recommends using a free and open-source alternative like Open VSX.

  1. Build the extension from source. There are several extensions freely available on GitHub that can be built into a VSIX file yourself and then installed via the --install-extension argument. Building third party extensions from source is outside of the scope of this document.

Posit Workbench does not provide support for external extensions. If you have questions or issues, we encourage you to check Stack Overflow, the extension’s repository, or the vscode repository.

Back to top