Extension Configuration

Workbench | Preview

Posit Workbench supports two ways to manage extensions based on your needs:

Default configuration

Posit Workbench includes a configuration file positron.extensions.conf which contains a list of extensions that administrators can modify. These extensions are installed for each user when they launch their first Positron Pro Session.

However, 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 preinstall extensions.

By default, the file contains the following extensions:

posit.shiny
posit.publisher

Customize the default configuration

Administrators can customize the extensions that are installed for each user by editing the positron.extensions.conf file. Administrators can add one, or several, extensions to the file, one extension per line.

If the extension is being installed from from Open VSX, the full extension ID and publisher needs to be included on the line with the extension.

For example, to install the latest version of the Databricks extension from Open VSX, include the following line in positron.extensions.conf:

databricks.databricks

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

/opt/positron-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 Workbench is installed in Kubernetes and Slurm environments.

Each line of the file is passed directly to positron-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):

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

Global extensions directory

To configure a global extensions directory, add the following line to positron.conf:

args=--extensions-dir=/opt/positron/extensions

Installation

Global extensions directory managed extensions

If your environment is configured with a global extensions directory, run rstudio-server install-positron-ext to install the extensions from positron.extensions.conf.

User-managed extensions

If users are managing their own extensions, Posit Workbench installs the extension list when a user launches a Positron Pro 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 Positron Pro session.

Extensions installed from Open VSX do not reinstall unless they are passed the --force argument in positron.extensions.conf. However, extensions installed from a local copy do reinstall 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.

Manual installation

If you have configured a global extensions directory, you can manually install extensions for your users. You may want to use the manual installation if you have several extensions in your global extensions directory, but only want to install specific ones for users.

When Positron Pro sessions are configured with a global extensions directory, users without write access to this directory cannot install extensions, and the extensions marketplace is disabled. Otherwise, users can manage their own extensions, and installs are performed on a per-user basis.

If you are a user that is managing your own extensions, see the Posit Workbench User Guide - Positron Pro > Guide > Extensions section for the installation methods that are available to you (including installing extensions from the marketplace using the Positron Pro UI).

The following options and examples require write access and are executed via command line:

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

  • To install the extension from Open VSX using Positron Server:

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

  • For example, when using a global extensions directory at /opt/positron-server/extensions, run the following command to install the Code Spell Checker extension:

    /usr/lib/rstudio-server/bin/positron-server/bin/positron-server --extensions-dir=/opt/positron-server/extensions --install-extension streetsidesoftware.code-spell-checker

    This can also be done from within a Positron Pro session via the UI.

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

  • First, download an extension in VSIX format from an online marketplace.

  • Then, install it using the --install-extension argument (like the example in Option 1) passing the VSIX file path as the extension name.

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

    /usr/lib/rstudio-server/bin/positron-server/bin/positron-server --extensions-dir=/opt/positron-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 Positron Pro. Posit strongly recommends using a free and open-source alternative like Open VSX.

Option 3: 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 as 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