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-269/ - 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 <version>

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

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

  2. Tag the image for your internal registry:

    docker tag rstudio/workbench-positron-init:<version> my-registry.example.com/workbench-positron-init:<version>

  3. Push the image to your internal registry:

    docker push my-registry.example.com/workbench-positron-init:<version>

  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"

Load-balanced deployments

When running Workbench in a load-balanced configuration, you must coordinate Positron upgrades across all nodes in the cluster.

Version parity requirement

Warning

All nodes in a load-balanced cluster must run the same Positron version.

Each Workbench node discovers its Positron version independently at startup by scanning the local installation directory. There is no cross-node version check or enforcement. If nodes have different Positron versions installed, users experience inconsistent behavior depending on the node handling their session.

Upgrade procedure for clusters

Perform the following steps on each node in the cluster:

  1. Download and install the new Positron version:

    sudo rstudio-server upgrade positron --version <version>

  2. Restart Workbench so that new sessions use the updated version:

    sudo rstudio-server restart

The order in which you upgrade nodes does not matter. However, until you upgrade and restart all nodes, users might encounter different Positron versions depending on which node handles their session.

Note

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

Verifying version consistency

After upgrading all nodes, verify that every node reports the same Positron version:

# Run on each node
sudo rstudio-server positron-version

All nodes should report identical version output. If any node reports a different version, check that:

  • The upgrade command completed successfully on that node
  • You restarted Workbench after the upgrade
  • No WORKBENCH_POSITRON_PATH environment variable or exe option in /etc/rstudio/positron.conf is overriding the version

Slurm deployments

When running Workbench with the Slurm Launcher plugin, Positron sessions run on Slurm compute nodes rather than on the Workbench node. You must install Positron on both the Workbench node and every compute node that might run a Positron session, and keep the versions in sync.

Topology

In a Slurm deployment:

  • Workbench node: Runs the Workbench service, serves the web UI, hosts the Positron documentation shown in the Help pane, and resolves the Positron executable path used to launch sessions on compute nodes. The Workbench node requires a full Positron installation even though it does not run Positron sessions itself.
  • Slurm compute node: Runs user Positron sessions as Slurm jobs and requires a full Positron installation.

Version parity requirement

Warning

The Workbench node and every Slurm compute node that might run a Positron session must all have the same Positron version installed.

When a user launches a Positron session, the Workbench node resolves the Positron executable path from its local installation and passes that path to the compute node running the session. The compute node runs that path directly without re-resolving it, so the same Positron version must be installed at the same location on every compute node. Mismatched versions can cause sessions to fail to launch, or can cause the Help pane documentation to not match the Positron version running the session.

Upgrade procedure for Slurm clusters

Step 1: Upgrade the Workbench node

On the Workbench node, install the new Positron version and restart Workbench:

sudo rstudio-server upgrade positron --version <version>
sudo rstudio-server restart

Step 2: Upgrade each Slurm compute node

Slurm compute nodes install only the Workbench session components, so the rstudio-server admin command is not available on the PATH. Invoke the upgrade CLI directly instead:

sudo /usr/lib/rstudio-server/bin/upgrade-cli positron --version <version>

Compute nodes do not require a service restart, since they do not run the Workbench service. New Slurm-launched sessions pick up the upgraded Positron version automatically.

Note

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

Air-gapped Slurm environments

If compute nodes cannot reach the Posit CDN, download the Positron archive on a machine with internet access and transfer it to each node. Then install from the local file:

# On the Workbench node
sudo rstudio-server upgrade positron --file /path/to/positron-workbench-linux-x64-<version>.tar.gz

# On each Slurm compute node
sudo /usr/lib/rstudio-server/bin/upgrade-cli positron --file /path/to/positron-workbench-linux-x64-<version>.tar.gz

Verifying version consistency

After upgrading, verify that the upgraded Positron version is present on the Workbench node and every compute node.

On the Workbench node, confirm the active version:

sudo rstudio-server positron-version

On each Slurm compute node, confirm that the upgraded version directory exists:

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

If a compute node is missing the upgraded version directory, re-run the upgrade-cli command on that node.

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 upgrade positron cleanup

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

sudo rstudio-server upgrade positron cleanup --keep <version>

To preview which versions would be removed without removing them:

sudo rstudio-server upgrade 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/<version>/

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.04.0-269) 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.04.0-269:

curl -O https://cdn.posit.co/positron/releases/pwb/x86_64/positron-workbench-linux-x64-2026.04.0-269.tar.gz
curl -O https://cdn.posit.co/positron/releases/pwb/arm64/positron-workbench-linux-arm64-2026.04.0-269.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-<version>.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-<version>.tar.gz

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

sudo rstudio-server upgrade positron \
  --file /path/to/positron-workbench-linux-x64-<version>.tar.gz \
  --docs-file /path/to/positron-workbench-docs-<version>.zip

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

sudo rstudio-server upgrade positron --docs-file /path/to/positron-workbench-docs-<version>.zip --version <version>

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