Upgrade

Workbench

These instructions describe the configuration requirements and how to upgrade Posit Workbench from a supported product version to the latest version.

To upgrade from Open Source to Workbench, follow the procedures available in the Upgrading from Open Source to Workbench section.

Upgrade requirements

Important

These instructions only cover upgrading Posit Workbench on the same server and between supported versions. If you are planning on changing servers or you are upgrading from an older, unsupported version, please see the How to Upgrade and/or Migrate Posit Team guide.

The following document covers adjustments that may need to be made to your configuration due to breaking changes between versions. To use this document, select the version you are currently on, or start at the oldest version that is newer than your version from the list below, and then follow the instructions until the end of the page:

With this release, Positron Pro sessions are moving from preview to General Availability (GA). The upgrade process will automatically back up any existing Positron Pro configuration files to ensure production-ready defaults are properly installed.

During package upgrade, the following files will be backed up if they exist:

  • /etc/rstudio/positron.conf as /etc/rstudio/positron.conf.bak
  • /etc/rstudio/positron-user-settings.conf as /etc/rstudio/positron-user-settings.conf.bak

After completing the package upgrade, carefully review the backed up files and the new default configuration files and merge any customizations as needed.

If your users have signed into GitHub within Positron (for GitHub Copilot, Pull Requests, or other GitHub integrations), they must sign out and sign back in to continue using Positron Assistant after upgrading to this version.

Direct users to the GitHub Copilot authentication change section of the 2026.01.1 User Guide for detailed instructions.

Positron Pro is now enabled by default on SUSE Linux 15 SP7 and openSUSE 15.6. On fresh installs, the default positron.conf and positron-user-settings.json configuration files are automatically generated, matching the behavior on other supported platforms. No action is needed if you are upgrading an existing installation that already has these files configured.

Positron Assistant provider and model settings have changed from a centralized format to per-provider individual settings. If you have configured any of the following settings in positron-user-settings.json or enforced-settings.json, they must be updated: - positron.assistant.enabledProviders — replace with individual positron.assistant.provider.<name>.enable settings (for example, positron.assistant.provider.amazonBedrock.enable: true) - positron.assistant.models.preference.byProvider — replace with individual positron.assistant.models.preference.<name> settings (for example, positron.assistant.models.preference.anthropic: "Claude Sonnet 4.5") - positron.assistant.models.custom — replace with individual positron.assistant.models.overrides.<name> settings (for example, positron.assistant.models.overrides.customProvider: [...])

Positron automatically migrates these settings in a user’s personal settings.json, but does not auto-migrate Workbench configuration files. See the Workbench Admin Guide for the updated settings.

  • Container image transition: Posit Workbench container images are moving from the rstudio/* Docker Hub organization to posit/* on Docker Hub (also published as ghcr.io/posit-dev/* on the GitHub Container Registry). Legacy rstudio/* images continue to be built during the transition. If you use the Workbench Helm chart, version 0.20.0 and later default to the new image repositories and include breaking changes. See the Helm chart Migrating to Posit Images guide for details.
  • Existing users must re-authenticate to each Custom OAuth integration after upgrading. Snowflake and Databricks integrations are unaffected.
  • Downgrading to a release older than 2026.05.0 (Golden Wattle) requires Custom OAuth users to re-authenticate. Snowflake and Databricks integrations are unaffected. On older releases, only the last Custom OAuth section for a given authorize or token URL is operational. Reduce the configuration to one integration per authorize or token URL before downgrading.
  • Administrators who previously enforced positron.assistant.enable in Positron settings should instead set assistant-enabled in /etc/rstudio/profiles; positron.assistant.enable will be deprecated in a future release. See Posit Assistant Admin Controls.
  • Proof Key for Code Exchange (PKCE) provides enhanced security during user logins when using OpenID Connect authentication, so it is enabled by default. It can be disabled if necessary by setting auth-openid-pkce-enabled=0 in rserver.conf.
  • Removed feature-flag-user-deletion. User deletion is officially supported.

The Positron version bundled with this release no longer supports the positron.assistant.enable setting, and Posit Assistant is enabled by default. If you used positron.assistant.enable in positron-user-settings.json or enforced-settings.json to control assistant availability, that setting is ignored after upgrading, and Posit Assistant becomes available to all users.

Before upgrading, set assistant-enabled in /etc/rstudio/profiles instead. It applies to both Positron Pro and RStudio Pro sessions. See Posit Assistant Admin Controls.

  • The Positron migration to the providers.json schema intentionally drops the positron.assistant.models.include setting (posit-dev/positron#14928). If you enforced it through positron-enforced-settings, it no longer restricts the models offered to Posit Assistant, leaving a gap in model enforcement. To restore the restriction, migrate to the ai-providers-enforced setting in /etc/rstudio/profiles, which points at a providers.json file. That schema matches models by exact name rather than by glob, so enumerate each model in the allow list. See AI Provider Admin Controls for details.
  • If you set posit-assistant-path, check that it points at a valid Posit Assistant installation. The search now ends if it does not find a valid installation, and RStudio reports Posit Assistant as not installed rather than falling back to the copy bundled with Workbench.
  • If you set posit-assistant-installation-enabled=0, users who had already installed Posit Assistant themselves are switched to the administrator-managed or bundled copy, which might be an older version. Their own copy is ignored, not removed.
  • If you enforce extensions.autoUpdate for Positron or VS Code sessions (e.g., via positron-enforced-settings), update it from the boolean false to the string "off". Code OSS 1.130.0 changed this setting from a boolean to a string enum, so a boolean value is no longer valid and the enforced setting will silently stop applying, falling back to Code OSS’s new default of "on".
  • If you set posit-assistant-path in rsession.conf, it is ignored after upgrading. rserver logs a warning at startup, and each session logs a warning. Remove the option from rsession.conf. The version that directory held is the version field of the package.json in it. Sessions run the newer of the copy bundled with Workbench and the version you select, so to keep that version it must be newer than the bundled copy, which rstudio-server upgrade posit-assistant list shows. If it is, install it with sudo rstudio-server upgrade posit-assistant --version <version>, or with --file from a local package. See Upgrading Posit Assistant for RStudio Pro.
  • If you installed Posit Assistant in /etc/rstudio/pai/bin, sessions no longer read it. If that version is newer than the bundled copy, install it with the same command.
  • A user’s existing copy in pai/bin under their RStudio data directory is neither read nor deleted. Sessions run the newer of the bundled copy and the version selected with rstudio-server upgrade posit-assistant, which might be older than the copy the user had in pai/bin. When sessions can reach cdn.posit.co and a newer version is available, the user is offered an update, and accepting it installs their own copy into pai/versions. To provide a specific version, install it with the upgrade command after upgrading Workbench, using --file in air-gapped environments. Sessions started before the install keep the copy they started with.
  • otel-logs-enabled and otel-traces-enabled now default to the value of otel-enabled instead of defaulting to off. A deployment that previously set only otel-enabled=1 – without explicitly setting either per-signal option – had both signals off before this release and now has both on, so it exports logs and traces to whatever destinations it has configured. Set otel-logs-enabled=0 and/or otel-traces-enabled=0 explicitly to keep exporting only a subset of signals.
  • When both otel-endpoint and otel-logs-endpoint are set in rserver.conf, logs are now sent to otel-logs-endpoint. Previously otel-endpoint took precedence for logs and otel-logs-endpoint was ignored, so a deployment that sets both will start sending log records – and the credentials in otel-logs-headers – to a collector that was inert before this release. To keep the previous routing, either remove otel-logs-endpoint, or set it to the otel-endpoint value with /v1/logs appended: unlike otel-endpoint, otel-logs-endpoint is used verbatim and gets no signal path added. Traces already behaved this way and are unchanged.
  • Workbench fails to start, or rejects a reload, when a numeric setting in /etc/rstudio/profiles has a non-numeric value. Check rserver.log after upgrading.
  • Workbench no longer reads the previously undocumented ai-providers-<name>-enabled, ai-providers-<name>-models-allow, and ai-providers-<name>-models-deny settings in /etc/rstudio/profiles. If you set them, they no longer restrict the providers or models available to Posit Assistant, and rserver.log reports each one as an unrecognized option. To keep these restrictions, set enabled and models.allow or models.deny for each provider in the providers.json file that ai-providers-enforced points to. See AI Provider Admin Controls for details.
  • (rstudio/launcher#1776) Kubernetes plugin: custom service.tpl templates that reference fields unknown at pod creation, such as host, render differently because the plugin creates the Service earlier. Set service-creation-mode=job-running to restore the earlier behavior.

Upgrade planning

Notify users ahead of time of the upgrade. You can use the admin notification feature.

Upgrade procedures

  1. Check if there are any active sessions running:

    Terminal
    sudo rstudio-server active-sessions
  • If there are active sessions, then suspend all active user sessions:

    Terminal
    sudo rstudio-server suspend-all
  1. Put the old version of the server into offline mode:

    Terminal
    sudo rstudio-server offline
  2. If you installed the SELinux policy module, upgrade it to the matching version:

If you previously disabled automatic updates, unlock the rstudio-workbench-selinux package:

Terminal
sudo dnf versionlock delete rstudio-workbench-selinux

Install the policy module package:

Terminal
sudo dnf install rstudio-workbench-selinux-2026.11.0+203.pro4

(Optional) To disable automatic updates again, lock the rstudio-workbench-selinux package:

Terminal
sudo dnf versionlock add rstudio-workbench-selinux

If you previously disabled automatic updates, unlock the rstudio-workbench-selinux package:

Terminal
sudo apt-mark unhold rstudio-workbench-selinux

Install the policy module package:

Terminal
sudo apt-get update
sudo apt-get install rstudio-workbench-selinux=2026.11.0+203.pro4

(Optional) To disable automatic updates again, lock the rstudio-workbench-selinux package:

Terminal
sudo apt-mark hold rstudio-workbench-selinux

For air-gapped (offline) environments, follow the installation procedure provided in the Access and Security - SELinux Configuration documentation to upgrade the SELinux policy module.

If you installed the SELinux policy module from source, follow the Building from source instructions.

  1. Upgrade the Workbench package:

If you previously disabled automatic updates, unlock the rstudio-server package:

Terminal
sudo dnf versionlock delete rstudio-server

Install the updated package:

Terminal
sudo dnf install rstudio-server-2026.11.0+203.pro4

(Optional) To disable automatic updates again, lock the rstudio-server package:

Terminal
sudo dnf versionlock add rstudio-server

If you previously disabled automatic updates, unlock the rstudio-server package:

Terminal
sudo apt-mark unhold rstudio-server

Install the updated package:

Terminal
sudo apt-get update
sudo apt-get install rstudio-server=2026.11.0+203.pro4

(Optional) To disable automatic updates again, lock the rstudio-server package:

Terminal
sudo apt-mark hold rstudio-server

If you previously disabled automatic updates, unlock the rstudio-server package:

Terminal
sudo zypper removelock rstudio-server

Install the updated package:

Terminal
sudo zypper install rstudio-server-2026.11.0+203.pro4

(Optional) To disable automatic updates again, lock the rstudio-server package:

Terminal
sudo zypper addlock rstudio-server

For air-gapped (offline) environments, follow this procedure instead.

Terminal (x86_64)
sudo dnf install ./rstudio-workbench-rhel-2026.11.0-203.pro4-x86_64.rpm
Terminal (ARM)
sudo dnf install ./rstudio-workbench-rhel-2026.11.0-203.pro4-aarch64.rpm
Terminal
sudo zypper install ./rstudio-workbench-2026.11.0-203.pro4-x86_64.rpm
Note

For older versions of RStudio/Workbench, please review the Previous Versions page.

  1. Restart the server:

    Terminal
    sudo rstudio-server restart
  2. Put the new version online:

    Terminal
    sudo rstudio-server online

The service will never be truly down (in the sense that users see a failure to connect). The offline mode keeps users from trying to start new sessions while you’re doing the upgrade.

Your configuration and settings remain unchanged from the previous version, and if you are running Workbench, your license status remains untouched as well.

NoteUpgrading Positron

You can upgrade Positron independently of Workbench using the CLI. See Upgrading Positron.

Downgrading

Important

These instructions cover downgrading (rolling back) Workbench on the same server between supported versions. This only works with the default SQLite3 database; Postgres databases need to revert to a previous snapshot.

  1. Notify users before the downgrade. For RStudio Pro sessions, you can use the Notifications feature.

  2. Check for active sessions:

    Terminal
    sudo rstudio-server active-sessions
  • If there are active sessions, then suspend all active user sessions:

    Terminal
    sudo rstudio-server suspend-all
  1. Put the old version of the server into offline mode:

    Terminal
    sudo rstudio-server offline
  2. Uninstall Workbench:

    If you previously disabled automatic updates, unlock the rstudio-server package:

    Terminal
    sudo dnf versionlock delete rstudio-server

    Remove the Workbench package:

    Terminal
    sudo dnf remove rstudio-server

    If you previously disabled automatic updates, unlock the rstudio-server package:

    Terminal
    sudo apt-mark unhold rstudio-server

    Remove the Workbench package:

    Terminal
    sudo apt-get remove rstudio-server

    If you previously disabled automatic updates, unlock the rstudio-server package:

    Terminal
    sudo zypper removelock rstudio-server

    Remove the Workbench package:

    Terminal
    sudo zypper remove rstudio-server

    If you installed the SELinux policy module, uninstall it as well:

    If you previously disabled automatic updates, unlock the rstudio-workbench-selinux package:

    Terminal
    sudo dnf versionlock delete rstudio-workbench-selinux

    Remove the policy module package:

    Terminal
    sudo dnf remove rstudio-workbench-selinux

    If you previously disabled automatic updates, unlock the rstudio-workbench-selinux package:

    Terminal
    sudo apt-mark unhold rstudio-workbench-selinux

    Remove the policy module package:

    Terminal
    sudo apt-get remove rstudio-workbench-selinux
  3. Download your preferred version of Workbench from our Supported Versions page. That page provides installation instructions for each version of Workbench. Follow those instructions as if it were a new Workbench installation.

  4. Finally, put the newly installed version in online mode:

    Terminal
    sudo rstudio-server online
Back to top