Upgrade
These instructions describe the configuration requirements and how to upgrade Posit Workbench from a supported product version to the latest version.
- We recommend that you upgrade to the latest version of Workbench. Please review the Release Notes prior to performing an upgrade.
- These upgrade procedures are not incremental, however, if you must upgrade to a previous supported version of Workbench, select your desired version below to verify that you are not using any deprecated configurations.
To upgrade from Open Source to Workbench, follow the procedures available in the Upgrading from Open Source to Workbench section.
Upgrade requirements
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.confas/etc/rstudio/positron.conf.bak/etc/rstudio/positron-user-settings.confas/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 toposit/*on Docker Hub (also published asghcr.io/posit-dev/*on the GitHub Container Registry). Legacyrstudio/*images continue to be built during the transition. If you use the Workbench Helm chart, version0.20.0and 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.enablein Positron settings should instead setassistant-enabledin/etc/rstudio/profiles;positron.assistant.enablewill 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=0inrserver.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.jsonschema intentionally drops thepositron.assistant.models.includesetting (posit-dev/positron#14928). If you enforced it throughpositron-enforced-settings, it no longer restricts the models offered to Posit Assistant, leaving a gap in model enforcement. To restore the restriction, migrate to theai-providers-enforcedsetting in/etc/rstudio/profiles, which points at aproviders.jsonfile. 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.autoUpdatefor Positron or VS Code sessions (e.g., viapositron-enforced-settings), update it from the booleanfalseto 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-pathinrsession.conf, it is ignored after upgrading. rserver logs a warning at startup, and each session logs a warning. Remove the option fromrsession.conf. The version that directory held is theversionfield of thepackage.jsonin 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, whichrstudio-server upgrade posit-assistant listshows. If it is, install it withsudo rstudio-server upgrade posit-assistant --version <version>, or with--filefrom 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/binunder their RStudio data directory is neither read nor deleted. Sessions run the newer of the bundled copy and the version selected withrstudio-server upgrade posit-assistant, which might be older than the copy the user had inpai/bin. When sessions can reachcdn.posit.coand a newer version is available, the user is offered an update, and accepting it installs their own copy intopai/versions. To provide a specific version, install it with the upgrade command after upgrading Workbench, using--filein air-gapped environments. Sessions started before the install keep the copy they started with. otel-logs-enabledandotel-traces-enablednow default to the value ofotel-enabledinstead of defaulting to off. A deployment that previously set onlyotel-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. Setotel-logs-enabled=0and/orotel-traces-enabled=0explicitly to keep exporting only a subset of signals.- When both
otel-endpointandotel-logs-endpointare set inrserver.conf, logs are now sent tootel-logs-endpoint. Previouslyotel-endpointtook precedence for logs andotel-logs-endpointwas ignored, so a deployment that sets both will start sending log records – and the credentials inotel-logs-headers– to a collector that was inert before this release. To keep the previous routing, either removeotel-logs-endpoint, or set it to theotel-endpointvalue with/v1/logsappended: unlikeotel-endpoint,otel-logs-endpointis 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/profileshas a non-numeric value. Checkrserver.logafter upgrading. - Workbench no longer reads the previously undocumented
ai-providers-<name>-enabled,ai-providers-<name>-models-allow, andai-providers-<name>-models-denysettings in/etc/rstudio/profiles. If you set them, they no longer restrict the providers or models available to Posit Assistant, andrserver.logreports each one as an unrecognized option. To keep these restrictions, setenabledandmodels.allowormodels.denyfor each provider in theproviders.jsonfile thatai-providers-enforcedpoints to. See AI Provider Admin Controls for details. - (rstudio/launcher#1776) Kubernetes plugin: custom
service.tpltemplates that reference fields unknown at pod creation, such ashost, render differently because the plugin creates the Service earlier. Setservice-creation-mode=job-runningto restore the earlier behavior.
Upgrade planning
Notify users ahead of time of the upgrade. You can use the admin notification feature.
Upgrade procedures
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
Put the old version of the server into offline mode:
Terminal
sudo rstudio-server offlineIf 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-selinuxInstall 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-selinuxIf you previously disabled automatic updates, unlock the rstudio-workbench-selinux package:
Terminal
sudo apt-mark unhold rstudio-workbench-selinuxInstall 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-selinuxFor 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.
- Upgrade the Workbench package:
If you previously disabled automatic updates, unlock the rstudio-server package:
Terminal
sudo dnf versionlock delete rstudio-serverInstall 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-serverIf you previously disabled automatic updates, unlock the rstudio-server package:
Terminal
sudo apt-mark unhold rstudio-serverInstall 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-serverIf you previously disabled automatic updates, unlock the rstudio-server package:
Terminal
sudo zypper removelock rstudio-serverInstall 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-serverFor air-gapped (offline) environments, follow this procedure instead.
Download the appropriate
.rpmfile on an internet-connected machine:- RHEL 10 (x86_64):
https://dl.posit.co/public/pro/rpm/el/10/x86_64/rstudio-workbench-rhel-2026.11.0-203.pro4-x86_64.rpm - RHEL 10 (ARM):
https://dl.posit.co/public/pro/rpm/el/10/aarch64/rstudio-workbench-rhel-2026.11.0-203.pro4-aarch64.rpm - RHEL 9 (x86_64):
https://dl.posit.co/public/pro/rpm/el/9/x86_64/rstudio-workbench-rhel-2026.11.0-203.pro4-x86_64.rpm - RHEL 8 (x86_64):
https://dl.posit.co/public/pro/rpm/el/8/x86_64/rstudio-workbench-rhel-2026.11.0-203.pro4-x86_64.rpm
- RHEL 10 (x86_64):
Securely copy the file to the air-gapped environment following your approved process.
Install the package:
Terminal (x86_64)
sudo dnf install ./rstudio-workbench-rhel-2026.11.0-203.pro4-x86_64.rpmTerminal (ARM)
sudo dnf install ./rstudio-workbench-rhel-2026.11.0-203.pro4-aarch64.rpmDownload the appropriate
.debfile on an internet-connected machine:- Ubuntu 26 (x86_64):
https://dl.posit.co/public/pro/deb/ubuntu/pool/resolute/main/r/rs/rstudio-server_2026.11.0+203.pro4/rstudio-workbench-2026.11.0-203.pro4-amd64.deb - Ubuntu 26 (ARM):
https://dl.posit.co/public/pro/deb/ubuntu/pool/resolute/main/r/rs/rstudio-server_2026.11.0+203.pro4/rstudio-workbench-2026.11.0-203.pro4-arm64.deb - Ubuntu 24 (x86_64):
https://dl.posit.co/public/pro/deb/ubuntu/pool/noble/main/r/rs/rstudio-server_2026.11.0+203.pro4/rstudio-workbench-2026.11.0-203.pro4-amd64.deb - Ubuntu 24 (ARM):
https://dl.posit.co/public/pro/deb/ubuntu/pool/noble/main/r/rs/rstudio-server_2026.11.0+203.pro4/rstudio-workbench-2026.11.0-203.pro4-arm64.deb - Ubuntu 22 (x86_64):
https://dl.posit.co/public/pro/deb/ubuntu/pool/jammy/main/r/rs/rstudio-server_2026.11.0+203.pro4/rstudio-workbench-2026.11.0-203.pro4-amd64.deb - Debian 13 (x86_64):
https://dl.posit.co/public/pro/deb/debian/pool/trixie/main/r/rs/rstudio-server_2026.11.0+203.pro4/rstudio-workbench-2026.11.0-203.pro4-amd64.deb
- Ubuntu 26 (x86_64):
Securely copy the file to the air-gapped environment following your approved process.
Install the package:
Terminal (x86_64)
sudo apt install ./rstudio-workbench-2026.11.0-203.pro4-amd64.debTerminal (ARM)
sudo apt install ./rstudio-workbench-2026.11.0-203.pro4-arm64.deb- Download the
.rpmfile on an internet-connected machine: - Securely copy the file to the air-gapped environment following your approved process.
Terminal
sudo zypper install ./rstudio-workbench-2026.11.0-203.pro4-x86_64.rpmFor older versions of RStudio/Workbench, please review the Previous Versions page.
Restart the server:
Terminal
sudo rstudio-server restartPut 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.
You can upgrade Positron independently of Workbench using the CLI. See Upgrading Positron.
Downgrading
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.
Notify users before the downgrade. For RStudio Pro sessions, you can use the Notifications feature.
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
Put the old version of the server into offline mode:
Terminal
sudo rstudio-server offlineUninstall Workbench:
If you previously disabled automatic updates, unlock the
rstudio-serverpackage:Terminal
sudo dnf versionlock delete rstudio-serverRemove the Workbench package:
Terminal
sudo dnf remove rstudio-serverIf you previously disabled automatic updates, unlock the
rstudio-serverpackage:Terminal
sudo apt-mark unhold rstudio-serverRemove the Workbench package:
Terminal
sudo apt-get remove rstudio-serverIf you previously disabled automatic updates, unlock the
rstudio-serverpackage:Terminal
sudo zypper removelock rstudio-serverRemove the Workbench package:
Terminal
sudo zypper remove rstudio-serverIf you installed the SELinux policy module, uninstall it as well:
If you previously disabled automatic updates, unlock the
rstudio-workbench-selinuxpackage:Terminal
sudo dnf versionlock delete rstudio-workbench-selinuxRemove the policy module package:
Terminal
sudo dnf remove rstudio-workbench-selinuxIf you previously disabled automatic updates, unlock the
rstudio-workbench-selinuxpackage:Terminal
sudo apt-mark unhold rstudio-workbench-selinuxRemove the policy module package:
Terminal
sudo apt-get remove rstudio-workbench-selinuxDownload 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.
Finally, put the newly installed version in online mode:
Terminal
sudo rstudio-server online