Upgrading Safely

Upgrades are routine maintenance, but they carry some risk: a config setting that gets renamed, an updated feature that breaks a workflow for one team, a node that comes back up on the wrong version. Treat every upgrade as a change that needs testing, a rollback plan, and a communication plan.

A safe upgrade, step by step

1. Read the release notes and breaking changes for every version between your current one and the target, not just the target version’s notes. Note any config settings that were removed or renamed; they’re the most common source of post-upgrade breakage.

   Tip

   On any page at https://docs.posit.co, you can click on Ask AI to summarize what changed between two versions and surface breaking changes.

2. Test on staging first. Stand up staging from a production backup (see Backups and staging), then run user acceptance testing with power users who exercise their real workflows: deploy and run a business-critical application end-to-end, and simulate simultaneous users running compute-heavy workloads. Staging only tells you something useful if it looks like production and gets used the way production is used.

3. Schedule and communicate (see Communication). Upgrade during low usage, not the middle of a reporting deadline or a training session.

4. Back up production (see Backups and staging) immediately before you upgrade. This is the backup you will restore from if the upgrade goes wrong, so take it right before to limit the chances of data loss.

5. Upgrade. The mechanics are shared across products:

   • If you run a recent version of the products, packages are version-held by default. Unhold, upgrade to a specific pinned version (never install “latest” unattended), then re-hold.
   • The new version installs over the old and preserves your configuration.
   • The service restarts.
   • In multi-node deployments, stop all nodes, upgrade all nodes, then bring them back up. Never run mixed versions across nodes, even briefly as it can lead to data corruption.

When you are several versions behind

Being several releases behind does not change the steps above.

• Release notes. Read the notes for every release between your current version and your target, not just the target’s. Removed and renamed configuration settings may accumulate, and they are the most common cause of a failed upgrade. The Ask AI button on https://docs.posit.co is useful to summarize changes and highlight breaking changes between your two versions.
• Backups. Make sure you have a backup of your server just before starting the upgrade.
• Staging. Restore production data from your backup onto a staging server, run the upgrade there, and have power users exercise their real workflows before you put it in production.

Package rebuilds are going to take some time. If you are also moving to a new Linux distribution, system libraries change underneath your existing R and Python packages, and those libraries have to be cleared and rebuilt. An OS upgrade also does not carry your R, Python, and Quarto installations forward; you reinstall each one. Pointing Workbench and Connect at Posit Package Manager, or at Posit Public Package Manager, before you start means those rebuilds install precompiled binaries instead of compiling from source, which is faster and make it easier to install required system dependencies.

Important

The product upgrade guides cover moving between supported versions on the same server. If your current version has already fallen out of the 18-month support window, or you are also changing servers or operating system, follow Upgrade and/or Migrate Posit Team instead.

That procedure does not upgrade in place. It stands up a new environment on staging while production stays online, configured to match production but without content, then migrates content and product databases into it in a second phase. Production must be shut down while those snapshots are taken. Save any architecture changes for a separate project afterward.

Guides on how to upgrade each product

Upgrade guides for each products are available in our documentation:

• Posit Connect
• Posit Workbench
• Posit Package Manager

Rollback reality

Each product requires a different rollback strategy. Taking a backup just before an upgrade is critical as it will be needed to get things running back up.

• Posit Connect: downgrade is not supported. The only way to revert is restoring the pre-upgrade backup.
• Posit Package Manager: there’s no downgrade path. Reverting means purging the installation, reinstalling the prior version, and restoring from backup. This is destructive, and it’s slow.
• Posit Workbench: downgrade is supported between supported versions, but only when you’re using the default SQLite database. If you’re running PostgreSQL, downgrading requires restoring a database snapshot taken before the upgrade.

When an upgrade misbehaves

In many cases, post-upgrade problems trace back to a configuration setting that was renamed or removed in the new version. Check the server log first. It will typically log a warning about any setting it doesn’t recognize. Update or remove that setting and restart.

If the logs don’t point to an obvious cause, or the fix doesn’t resolve it, open a support ticket (see Getting help) rather than trying to work around the issue in production.

Upgrading the language runtime (R, Python, Quarto, and Node.js)

Upgrading a language runtime is a separate job from upgrading the product, and it splits into two distinct tasks that do not need to be completed at the same time:

1. Adding a new version is something you can do at any time. Both Connect and Workbench are built to run several versions of each runtime side by side.
2. Removing an old version. requires an audit of what still depends on that version before removing it. Most of the time this only requires to update the project’s environment specifications. Removing a runtime environment required by content on Connect will lead to deployment failures.

Do the first on its own schedule. If you upgrade the products on a monthly or quarterly cadence, you can combine adding the latest versions of the runtimes to the product upgrades. The second requires admins to audit the content published on Connect and communicating with your users before removing an older version.

Adding a version

Connect resolves each content item to a runtime version at deploy time and keeps that association for the life of the deployment. Installing a newer version does not affect existing content. Only content deployed or rebuilt after the install can pick it up. That is what makes adding a version safe.

The steps are the same for every runtime:

1. Install the new version into a version-specific directory, alongside the versions you already have. Follow Posit’s instructions for R, Python, Quarto, and Node.js. These install to versioned paths (/opt/R/4.5.1, /opt/python/3.13.1, and so on), which is what lets versions coexist.
2. Tell the server the new version exists by editing the configuration files.
3. Restart the service.

Warning

Do not install runtimes from your Linux distribution’s package manager (apt, yum, zypper). They install a single version under a shared path, so the next OS update overwrites it in place. When a runtime disappears from under deployed content, Connect has to rebuild every package for that content on the next render or the next request, and some packages will not rebuild. You get an unplanned version removal instead of an upgrade.

For Connect, while R versions can be discovered automatically, we recommend to list manually in /etc/rstudio-connect/rstudio-connect.gcfg the versions you want to expose to your users, which also the pattern used for the other runtimes (Python, Quarto, and Node.js).

Connect analyzes the installations at startup and logs the versions it found and whether it can use each one. Read those log lines after the restart. If Connect cannot use an executable you listed, it fails to start rather than starting without it.

Two things are specific to Node.js: running Node.js content requires the Advanced license tier, and the minimum supported version is 22.18.0. Posit tests against the Active LTS and Maintenance LTS lines, so prefer those.

For Workbench, users choose the versions of R and Python they want to use for their project. They select the version of the interpreter from the IDE they use, and for Python, use virtual environments. Typically, users will use the version of Quarto made available in their PATH. It is however possible to have multiple versions installed that would then be called by the users using the full executable paths.

Note

If you run Worbench or Connect on Kubernetes, none of this applies to the filesystem. The available runtime versions are whatever the configured execution environment images provide, and adding a version means building a new image and registering it.

Removing a version

Content that resolved to a version you delete has to have all of its packages rebuilt against a different version. That rebuild happens on demand: at the next scheduled render, or the first time someone opens the application. It can fail because not every package installs cleanly on a newer R or Python, and native npm modules often need updating across a Node.js major version.

So you will need to audit first, and communicate your findings to the authors of the content so they can test their application with a newer version. Connect records the version each content item resolved to and exposes it as r_version, py_version, quarto_version, and node_version on the content item in the API. Pull those for all your content and find what still points at the version you want to retire. Viewing content runtime settings has working examples. The Connect Gallery has also a Shiny application, “Runtime Version Scanner”, that lists the versions of R, Python, and Quarto each content item a user owns or collaborates on.

With that list in hand:

1. Contact the owners of the affected content. Abandoned content can be deleted.
2. For content worth keeping, redeploy it against a supported version and confirm it still works. You can also force the rebuild ahead of time with rsconnect content build from rsconnect-python, so you can test redeployements directly.
3. Remove the version, and its configuration entry, only once nothing depends on it.

Upgrading the Posit Professional Database Drivers

Posit releases new versions of the Professional drivers on a regular cadence. We strongly recommended to regurlaly update the drivers to prevent security and administrative issues.

If you installed the drivers using the instructions provided, new versions of the drivers will be available through your Linux distribution’s package manager.

More information is available on the Professional Drivers installation page.