Extension Configuration

Workbench

In a default Posit Workbench installation, VS Code is preconfigured to include the following extensions for all users:

vscode.extensions.conf
quarto.quarto
posit.shiny
posit.publisher

These extensions are defined in the configuration file vscode.extensions.conf, and can be modified by the administrator. These extensions will be installed for each user when they launch their first VS Code Session.

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.

You can control how extensions become available in users’ environments through two primary approaches:

User-managed extensions

By default, users can install extensions to their home directory from the Open VSX Registry. See the Posit Workbench User Guide > VS Code > Extensions section for the installation methods available.

You can choose to pre-configure additional extensions to be installed in all users’ environments by modifying the vscode.extensions.conf file in your configuration directory. Populate the file with a list of extensions to be installed for each user from https://open-vsx.org/ at session launch.

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/vscode/extensions --install-extension <test-line>

When users manage their own extensions, Workbench evaluates the vscode.extensions.conf file at the start of every VS Code session. Users might notice a delay when launching their first VS Code session while these extensions install. In later sessions, Workbench does not reinstall extensions from Open VSX unless the --force argument is specified in the vscode.extensions.conf file.

However, Workbench reinstalls extensions from local copies at every launch, which can slow down all sessions. To avoid these performance issues, consider configuring a global extension directory.

Centralized extension management

When VS Code is configured to use a global extensions directory, only users with write access to that directory can install extensions from the Open VSX marketplace. All other users will have marketplace access disabled and can only access the extensions you have installed in the global extension directory.

To configure VS Code extensions to be centrally managed:

  1. Create a directory path for the global extensions directory, e.g., /opt/vscode/extensions. This directory should be readable and executable by all users, but only permit write access to users that will administer the global directory for all users.

  2. Add the following line to vscode.conf:

    vscode.conf
    args=--extensions-dir=/opt/vscode/extensions

    If there are already existing arguments set for this value, append --extensions-dir to the end, (e.g., args=--host=0.0.0.0 --extensions-dir=/opt/vscode/extensions)

  3. Restart Posit Workbench so that the changes to vscode.conf are detected.

  4. Install the desired extensions in this directory using one of the options in Manual extension installation below.

Copying extension files into the global extensions directory is not sufficient for installation. You must follow the instructions and commands in the next sections to properly install extensions. This process creates an extensions.json file in the extensions directory, which VS Code requires to load and recognize the extensions during user sessions.

Manual extension installation

Install extensions into the global extensions directory using any of the following options. These methods require write access to the extensions directory for either the Linux user or Workbench user:

Option 1: Install the extension from Open VSX using Code Server

Use this option when the administrator has access to Open VSX. This method will ensure that the version of the extension is compatible with the version of code-server.

  1. Start a VS Code session with a Workbench user account that has write access to the global extensions directory

  2. Install the desired extension from Open VSX using the Extensions pane in the VS Code session UI.

Alternatively, you can install the extension directly from the command line without starting a VS Code session. Run the following, replacing the <extension-publisher>.<extension-name> with the desired extension’s values:

/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server --extensions-dir=/opt/vscode/extensions --install-extension <extension-publisher>.<extension-name>

This can also be done from within a VS Code session via the UI by an administrator with write access to the global extensions directory.

Option 2: Download an extension in VSIX format from an online marketplace and install it

Use this option if the server does not have access to Open VSX.

  1. Download an extension in VSIX format from an online marketplace. You will need to verify compatibility between the extension version and your version of pwb-code-server. See Extension version compatibility below for additional guidance.

  2. Copy the extension to the global extensions directory.

  3. Install the extension using the VSIX file path as the extension name:

/usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server --extensions-dir=/opt/vscode/extensions --install-extension <VSIX file path>
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.

Option 3: Install a list of extensions from in vscode.extensions.conf

Use this option to install multiple extensions with one command. The extensions can be installed directly from Open VSX or from downloaded VSIX files.

  1. Modify the vscode.extensions.conf configuration file to 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. If the extension is a local VSIX file, specify the path to the local file.

    For example:

    vscode.extensions.conf
    # example of extensions to be installed from Open VSX
quarto.quarto
REditorSupport.r@2.6.1

# example of local VSIX files to be installed
/opt/vscode/extensions/company-extension-1.0.1.vsix

  2. Run the following to install the extensions listed in the vscode.extensions.conf file:

    rstudio-server install-vs-code-ext
Option 4: 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.

However, Posit does not provide support for external extensions, so building third-party extensions from source is outside of the scope of this document. If you have questions or issues, we encourage you to check Stack Overflow, the extension’s repository, or the vscode repository.

Extension version compatibility

When installing extensions directly from Open VSX, the registry will provide the extension version that is compatible with your code-server version.

However, when operating in an offline environment, VSIX extension files must be downloaded manually from the Open VSX registry. The registry’s default download is always the latest version of the extension. This version might be incompatible with your specific code-server version, leading to installation failure.

To ensure compatibility, you must manually find and download a compatible version:

  1. Identify your Code Server version. From the command line, run:

    /usr/lib/rstudio-server/bin/pwb-code-server/bin/code-server --version

    The output will look like:

    2025.04-b13169 PWB with Code: 1.99.0
64f955d664252926aec1e1d4b76e7b622085ab3a

    The Code Server version is the string following Code:.

  2. On the extension’s Open VSX page, review the extension metadata for available versions to identify the version that matches your code-server’s engine version.

Back to top