Upgrade within the Retool 4.x line (Helm)

Upgrade an existing self-hosted Retool 4.x Helm instance to a later 4.x stable release.

This guide covers upgrading an existing self-hosted Retool Helm + Kubernetes instance that's already running Retool 4.0 or later to a later 4.x stable release (for example, 4.0 to 4.34). It doesn't cover the new-service setup (agent sandbox, JS executor, MCP server, blob storage, app builder) that a 3.x instance needs the first time it reaches 4.0.

note

Still running Retool 3.x? Use Upgrade from Retool 3.x to 4.0 (Helm) instead.

Before you upgrade

Choose your target version

Keeping your deployment up-to-date ensures your organization has access to newer features and security updates. Running a deployment that is multiple releases behind the current one makes each upgrade riskier. Changelogs accumulate more breaking changes and deprecations, incremental migration becomes harder to test, and a large version jump can skip over a release with a required migration step.

If your deployment is more than one stable release behind, upgrade through each stable release in sequence rather than jumping directly to your target version. For example, to upgrade from 3.300 to 4.34:

3.300 -> 3.334 -> 4.0 -> 4.34

Verify each installation before proceeding to the next release. Review the Stable releases or Edge releases page and read all changelogs between your current version and your target version before starting.

Upgrading sequentially through each release is another reason to keep your deployment current: the fewer releases you're behind, the fewer intermediate upgrades you need to perform.

Update the Helm chart repository

The Helm chart version and the Retool app version aren't tied to each other. Chart releases ship independently, and the app version you run is set separately by the image.tag value below. Update your local chart cache:

helm repo add retool https://charts.retool.com
helm repo update

Terraform

Set the new chart version in your helm_release resource, using the chart version you want to run:

resource "helm_release" "retool" {
  repository = "https://charts.retool.com"
  chart      = "retool"
  version    = "<latest-chart-version>"
  # ...
}

Update the image tag

Update image.tag in your values.yaml to your target release. The stable release is 4.34.0-stable:

image:
  tag: X.Y.Z-stable  # use your target version

No other rr.* or mcp.* values changes are required for an incremental 4.x upgrade. Your existing 4.0 configuration carries forward unchanged. Later chart versions do add new opt-in values (for example, AppArmor profile installers as a seccomp alternative, and an npm registry proxy for the agent sandbox), but they default to off and don't require any action. Check a release's changelog if you want to adopt one of these newer options.

Apply the changes

If you don't already know your release name, list it first:

helm list

Then run the upgrade, substituting your release name:

helm upgrade <your-release-name> retool/retool \
  --version <latest-chart-version> \
  -f values.yaml

Verify the upgrade

Once the instance is healthy, open the profile menu in the top-right corner to confirm the version matches your target release, and spot-check your critical apps, queries, and workflows. Refer to Self-hosted Retool upgrade best practices for broader testing guidance.