Upgrading Positron

Workbench

Overview

Posit Workbench includes a CLI tool that lets administrators upgrade Positron independently of Workbench package upgrades. This is useful for deploying new Positron releases without waiting for or performing a full Workbench upgrade.

Installation layout

Workbench installs Positron versions under /usr/lib/rstudio-server/bin/positron-server/. The bundled/ directory contains the version shipped with your Workbench package, and the CLI stores each additionally installed version in its own versioned directory:

  • /usr/lib/rstudio-server/bin/positron-server/
    • bundled/ - Version shipped with Workbench
      • bin/
        • positron-server
    • 2026.04.0-55/ - Installed via CLI
      • bin/
        • positron-server

Version selection

Workbench automatically detects which Positron version to use. You do not need to change any configuration after upgrading. The resolution order is:

  1. The WORKBENCH_POSITRON_PATH environment variable, if set
  2. The exe option in /etc/rstudio/positron.conf, if configured
  3. The most recent version found by scanning all subdirectories (including bundled/) under the installation directory

Upgrade procedure

Install a specific version

To download and install a specific Positron version:

sudo rstudio-server upgrade positron --version 2026.02.0-109

Restart Workbench

After upgrading, restart Workbench so that new sessions use the updated version:

sudo rstudio-server restart
Note

The upgrade does not affect existing running sessions. Users must start a new session to use the upgraded version.

Verifying the installation

Check the currently active Positron version:

sudo rstudio-server positron-version

List all installed versions by inspecting the installation directory:

ls /usr/lib/rstudio-server/bin/positron-server/

Advanced options

Force reinstall

To reinstall a version that is already present (performing a clean reinstall):

sudo rstudio-server upgrade positron --version 2026.02.0-109 --force

Kubernetes deployments

In Kubernetes deployments, you upgrade Positron by changing the version in your Helm chart values and redeploying. A standalone Positron init container delivers the binaries to both the server pod and session pods at startup. The CLI tool described above is not used in this environment.

This section assumes you are using the Workbench Helm chart to manage your deployment. For a full list of available chart values, see the chart README.

Helm chart configuration

To enable a specific Positron version, set components.positron.version in your values.yaml, yaml components: positron: version: "2026.04.0-269"

This value controls both the init container image tag and the server-side mount path where Positron binaries are installed.

To upgrade to a newer Positron version, update the version and run helm upgrade:

helm upgrade my-release rstudio/rstudio-workbench -f values.yaml
Note

Existing running sessions are not affected by the upgrade. Users must start a new session to use the updated version.

How it works

When components.positron.version is set, the Helm chart:

  1. Runs a Positron init container on the server pod that copies Positron binaries to an emptyDir volume mounted at /usr/lib/rstudio-server/bin/positron-server/{version}.
  2. Configures rserver.conf so the launcher injects the same Positron init container into session pods, making the binaries available to user sessions.

The Positron init container works alongside the existing session init container (rstudio/workbench-session-init), which delivers Workbench session components. For more information on session init containers, see Session init container.

Private registry / air-gapped environments

If your environment cannot pull images from Docker Hub, you can host the Positron init container image in an internal registry.

  1. Pull the official image from Docker Hub:

    docker pull rstudio/workbench-positron-init:2026.04.0-269

  2. Tag the image for your internal registry:

    docker tag rstudio/workbench-positron-init:2026.04.0-269 my-registry.example.com/workbench-positron-init:2026.04.0-269

  3. Push the image to your internal registry:

    docker push my-registry.example.com/workbench-positron-init:2026.04.0-269

  4. Override the image repository in your values.yaml:

    components:
  positron:
    version: "2026.04.0-269"
    image:
      repository: "my-registry.example.com/workbench-positron-init"

Managing versions

Cleaning up old versions

Use the positron cleanup subcommand to remove old non-bundled versions. The bundled version is never removed.

sudo rstudio-server positron cleanup

This lists the versions that will be removed and prompts for confirmation. To preserve a specific version alongside bundled:

sudo rstudio-server positron cleanup --keep 2026.02.0-109

To preview which versions would be removed without removing them:

sudo rstudio-server positron cleanup --dry-run
Warning

Before confirming, verify that the versions being removed are not in use by the server or any active sessions. Check the active version with sudo rstudio-server positron-version.

Workbench package upgrades

When you upgrade the Workbench package itself (e.g., via apt or yum):

  • The new package replaces the bundled/ directory with its included version.
  • Versions you installed via the CLI persist and remain available.

Reverting to the bundled version

To revert to using only the version bundled with Workbench, remove the CLI-installed version directories:

sudo rm -rf /usr/lib/rstudio-server/bin/positron-server/2026.02.0-109/

After removing the extra versions, restart Workbench:

sudo rstudio-server restart

Workbench will fall back to the bundled/ version per the version selection order.

Install from a local archive

You can install Positron from a locally available archive file instead of having the CLI download it automatically. This is useful in air-gapped or offline environments, or networks with restricted outbound access.

Download the archive

On a machine with internet access, download the Positron archive from the Posit CDN. Archives follow this URL pattern:

https://cdn.posit.co/positron/releases/pwb/{arch}/positron-workbench-linux-{arch_abrv}-{version}.tar.gz

Replace {version} with the target version (e.g., 2026.02.0-109) and use the architecture values from the table below:

Architecture {arch} (URL path) {arch_abrv} (filename)
x86_64 x86_64 x64
arm64 arm64 arm64

For example, to download version 2026.02.0-109:

curl -O https://cdn.posit.co/positron/releases/pwb/x86_64/positron-workbench-linux-x64-2026.02.0-109.tar.gz
curl -O https://cdn.posit.co/positron/releases/pwb/arm64/positron-workbench-linux-arm64-2026.02.0-109.tar.gz

Download the docs bundle (optional)

Docs bundles are architecture-independent and available at:

https://cdn.posit.co/positron/releases/docs/positron-workbench-docs-{version}.zip

For example:

curl -O https://cdn.posit.co/positron/releases/docs/positron-workbench-docs-2026.02.0-109.zip

Install the archive

After transferring the files to the target server, install with --file:

sudo rstudio-server upgrade positron --file /path/to/positron-workbench-linux-x64-2026.02.0-109.tar.gz

To also install a local docs bundle, add --docs-file:

sudo rstudio-server upgrade positron \
  --file /path/to/positron-workbench-linux-x64-2026.02.0-109.tar.gz \
  --docs-file /path/to/positron-workbench-docs-2026.02.0-109.zip

To install only the docs bundle for an already-installed version:

sudo rstudio-server upgrade positron --docs-file /path/to/positron-workbench-docs-2026.02.0-109.zip --version 2026.02.0-109

Troubleshooting

Version not detected after upgrade

If positron-version does not report the expected version after upgrading:

  • Verify the version directory exists under /usr/lib/rstudio-server/bin/positron-server/.
  • Check that the exe option in /etc/rstudio/positron.conf is not set to a hardcoded path pointing to a different version. If exe is set, it takes precedence over auto-detection.
  • Restart Workbench with sudo rstudio-server restart.

Download failures

If the download fails during an upgrade:

  • Verify the server has outbound internet access to Positron’s CDN.
  • Check proxy settings if your environment requires an outbound proxy.
  • Use --file to install from a locally downloaded archive as a workaround.

Permission errors

The upgrade positron command requires root privileges. Always run with sudo:

sudo rstudio-server upgrade positron --version <version>
Back to top