Extension Configuration

Workbench | Preview

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

Default configuration

By default, users can install extensions to their home directory from the Positron Extension Marketplace.

Positron comes preconfigured with two categories of extensions:

  1. Built-in extensions: These extensions are built into the Positron source code. To view the complete list, start a Positron Pro session, open the Marketplace, and filter by @builtin .

  2. Bootstrap extensions: These extensions are bundled as .vsix files in Positron and installed to a user’s home directory when they launch their first Positron session. To view bootstrapped extensions, launch a Positron Pro session for a user that hasn’t installed any extensions, and open the Marketplace. Do not type in a filter. All visible extensions are bootstrap extensions. Users can upgrade, uninstall, enable, and disable these extensions on their own.

Pre-configuring extensions

There are two methods administrators can use to pre-configure extensions to be installed in their users’ environments:

  1. Bootstrap extensions: Add .vsix files to the Positron bootstrap extensions directory so they are installed for each user on their first session launch alongside the Positron-bundled bootstrap extensions. We highly recommend using this method to avoid relying on network calls to Open VSX.

  2. Install from Open VSX at session launch: Create a positron.extensions.conf file in your configuration directory and populate this with a list of extensions to be installed for each user from https://open-vsx.org/ at session launch. This method is similar to how we recommend you pre-configure VS Code extensions for users.

Bootstrap extensions

To configure additional bootstrap extensions, download each extension .vsix file from the desired location (we recommend starting with https://open-vsx.org/ or the extension’s GitHub page), to /usr/lib/rstudio-server/bin/positron-server/extensions/custom-bootstrap. 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.

Note

Positron only installs bootstrap extensions on each user’s first session launch after Positron has been initially installed or upgraded. If your users have already launched Positron Pro sessions and you want to ensure they get the new extensions before the next Positron upgrade, instruct them to remove the hidden file from their Positron User Data Directory. The default location for this file is at ~/.positron-server/extensions/.version or consider using a positron.extensions.conf file.

Install from Open VSX at session launch

Administrators can create a positron.extensions.conf file with a list of extensions to install from Open VSX when a user launches their first Positron Pro session. The list should include one extension per line with the format ${publisher}.${name}.

This approach requires Workbench to have network access to Open VSX. 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.

While it is possible to include paths to .vsix files in this configuration file, if you are installing from .vsix we highly recommend using the Bootstrap extensions approach instead. Bootstrap extensions include version management that prevents .vsix files from being re-installed when the user already has them installed. Additionally, they prevent session launch delays.

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

databricks.databricks

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:

positron-server --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

Then install all desired extensions to this directory following the directions in Manual installation.

Installation

User-managed extensions

If users are managing their own extensions, they can install extensions directly from the Extensions Marketplace within Positron Pro sessions. 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).

Manual installation

When Positron Pro sessions are configured with a global extensions directory, users without write access to the global extensions directory cannot install extensions, and the extensions marketplace is disabled.

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 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

  • 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