Extension Configuration

Workbench

Positron Pro comes preconfigured with two categories of extensions:

  1. Built-in extensions: These extensions are built into the Positron Pro 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 Pro and installed to a user’s home directory when they launch their first Positron Pro 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.

You can control how additional extensions become available in users’ environments:

User-managed extensions

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

You can choose to pre-configure additional extensions in users’ environments. These extensions will be installed for every user. There are two methods to pre-configure extensions, detailed in the following sections:

  1. Custom bootstrap extensions: Add .vsix files to the Positron Pro custom bootstrap extensions directory so they are installed for each user on their first session launch alongside the Positron Pro-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.

Custom bootstrap extensions

To configure custom 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 /etc/rstudio/positron-custom-bootstrap. These extension files must exist on the node where the session is launched, which might differ from where Workbench is installed in Kubernetes and Slurm environments.

Note

Positron Pro only installs bootstrap extensions on each user’s first session launch after Positron Pro 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 Pro upgrade, instruct them to remove the hidden .version file from their Positron Pro User Data Directory. The default location for this file is at ~/.positron-server/extensions/.version. Alternatively, 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 custom 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:

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>

Centralized extension management

When Positron Pro 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 Positron Pro extensions to be centrally managed:

  1. Create a directory path for the global extensions directory, e.g., /opt/positron/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 positron.conf:

    positron.conf
    args=--extensions-dir=/opt/positron/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/positron/extensions)

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

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

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 Positron Pro requires to load and recognize the extensions during user sessions.

Manual extension installation

When using a global extensions directory, Positron’s preconfigured bootstrap extensions will not be automatically installed for users. You must install these explicitly, in addition to any other extensions you wish to provide.

Install Positron bootstrap extensions

Install the Positron bootstrap extensions by starting a Positron Pro session with a user account that has write access to the global extensions directory. This will install all Positron bootstrap extensions into the global extensions directory and make them available for all users.

Alternatively, if you do not have a Workbench user account with write access to the global extensions directory, you can install the Positron bootstrap extensions manually. Run the following commands in the terminal as a Linux user with write access to the global extensions directory:

  1. Find all Positron bootstrap extension .vsix files located in /usr/lib/rstudio-server/bin/positron-server/bundled/extensions/:

    find "/usr/lib/rstudio-server/bin/positron-server/bundled/extensions" -name "*.vsix"

  2. For each .vsix file found, run the following command to install the extension into the global extensions directory. Replace <VSIX file path> with the path to each .vsix file found in the previous step:

    /usr/lib/rstudio-server/bin/positron-server/bundled/bin/positron-server --extensions-dir=/opt/positron/extensions --install-extension <VSIX file path>

Install additional extensions

You can install additional 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 Positron Pro 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 positron-server.

  1. Start a Positron Pro 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 Positron Pro session UI.

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

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

Option 3: Install a list of extensions from in positron.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 positron.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:

    positron.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/positron/extensions/company-extension-1.0.1.vsix

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

    rstudio-server install-positron-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 positron-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 positron-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/positron-server/bundled/bin/positron-server --version

    The output will look like:

    Positron: 2025.06.0 build 167
Positron SHA: e7e5d5590adc6bf7b760f837051cd2f57ea9e3dc
Code OSS: 1.100.0
Arch: x64

    The Code Server version is the value in Code OSS.

  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.

Troubleshooting

Positron Pro sessions do not start correctly

Ensure that the global extensions directory has a valid extensions.json file. If this file is missing or corrupted, Positron Pro sessions might fail to start correctly. When you install extensions using the methods described in this document, Workbench creates a valid extensions.json file.

You can also manually create an empty extensions.json file to allow sessions to start without any extensions installed. To create an empty extensions.json file, run the following command with a Linux user that has write access to the global extensions directory:

echo '[]' > <PATH-TO-GLOBAL-EXTENSIONS-DIRECTORY>/extensions.json

Positron built-in and bootstrapped extensions are not available

  • The global extensions directory must be executable by all users.
  • All extension folders must be readable by all users.
  • You have installed the Positron bootstrap extensions into the global extensions directory. See Install Positron bootstrap extensions for instructions.

Expected extensions are not available

When using a global extensions directory, users only see extensions installed by the administrator into the global extensions directory. Verify that:

  • The desired extensions have been installed into the global extensions directory using one of the methods described in this document.
  • The global extensions directory is executable by all users.
  • All extension folders are readable by all users.

Extension fails to install due to version incompatibility

When installing extensions directly from Open VSX, the registry provides the extension version that is compatible with your positron-server version. If you are operating in an offline environment, you must manually download VSIX extension files from the Open VSX registry.

The registry’s default download is always the latest version of the extension, which might be incompatible with your specific positron-server version, leading to installation failure. Review the Extension version compatibility section for instructions on how to identify and download a compatible extension version.

Back to top