Migrating from Helm 3 to Helm 4

Kubernetes delivery that holds up? WZ-IT builds and operates GitOps, CI/CD and platform building blocks - from Helm and Argo CD through registry and policies to reproducible rollouts. See Platform Engineering

Helm is the de-facto package manager for Kubernetes, and with Helm 4 the first new major generation in six years is here. The good news first: the switch is far gentler than the notorious jump from Helm 2 to Helm 3. Helm 4 takes over existing releases with no migration step. The less good news: there is a set of breaking changes that strike silently - especially --wait, post-renderers and CI/CD scripts. And the clock on Helm 3 is ticking.

This guide shows what changes, what stays the same and what a low-risk, plannable switch looks like. As of July 2026.

Table of contents

• Why now: the EOL clock on Helm 3
• The good news: no break with your existing releases
• What Helm 4 changes: the breaking changes
• Charts: what stays, what is experimental
• The low-risk migration path
• Four stumbling blocks

Why now: the EOL clock on Helm 3

Helm 4.0 was released as General Availability on 12 November 2025 at KubeCon North America (Helm blog). That starts the wind-down of Helm 3 on a fixed schedule:

• 9 September 2026: the last, limited Helm 3 feature release. It contains only Kubernetes client library updates to support new Kubernetes versions. No other features will be backported.
• 10 February 2027: end of security support. After that, Helm 3 receives no updates at all, including no security patches (Helm blog: End of Life).

Important for planning: these dates were officially extended in June 2026. The original GA blog post still named November 2026 as the end of support. Anyone relying on older secondary sources is working with the wrong deadlines - the authoritative dates are 9 September 2026 and 10 February 2027.

So the pressure is not acute like a security incident, but it is plannable: by early 2027, Helm 3 should be replaced in production pipelines and clusters. That is enough time for a controlled switch - and enough reason not to keep pushing it back.

The good news: no break with your existing releases

The jump from Helm 2 to Helm 3 was painful because the storage format changed and every release had to be migrated with the 2to3 plugin. Helm 4 is different.

Helm 4 manages existing Helm 3 releases with no migration step. The storage format of the release secrets in the cluster is identical; there is no conversion tool and no migration run. In practice it is an in-place CLI upgrade: you swap the binary, and Helm 4 sees the same cluster state that Helm 3 saw before.

One detail operations teams still need to know: the apply method. New releases installed with Helm 4 default to server-side apply. Existing releases created by Helm 3, however, stay on client-side apply after the switch - on upgrade or rollback, Helm 4 follows each release's previous method. So after the migration, two apply models run side by side in one cluster. For most charts this is unremarkable, but it can matter with field-ownership conflicts.

What Helm 4 changes: the breaking changes

Helm 4 deliberately introduces backward-incompatible changes to the CLI, flags and SDK. The four that matter most in practice:

1. --wait requires additional RBAC. Helm 4 uses the kstatus library for --wait, which needs the watch verb in addition to list on all chart resources (HIP-0022). If the permission is missing, --wait operations fail immediately. This is the first stumbling block right after swapping the binary.

2. Post-renderers are now plugins. An executable path can no longer be passed directly to helm ... --post-renderer; it must be a plugin name. Anyone wiring in Kustomize or custom scripts as a post-renderer (common in GitOps setups) has to rewire that before the migration.

3. helm registry login and renamed flags. In v4, the OCI login accepts only the domain name without a path. Additionally, flags were renamed: --atomic becomes --rollback-on-failure, --force becomes --force-replace. The old flags still work but emit a deprecation warning; --create-pods is removed entirely.

4. New SDK import path. Anyone using Helm as a Go library must switch to the import path helm.sh/helm/v4. The stable SDK is code-incompatible with v3, and logging runs through slog. This affects custom tools and operators that call Helm programmatically (Helm 4.0 release notes).

Details on these changes are in the Helm 4 overview.

Charts: what stays, what is experimental

For most teams this is the most reassuring part: existing charts with apiVersion: v2 run unchanged under Helm 4. That is the vast majority of all charts today. There is no need to rewrite charts.

Helm 4 does introduce a new chart format v3, but it is explicitly experimental in 4.0. It is disabled by default and only reachable via HELM_EXPERIMENTAL_CHART_V3=1 and helm create --chart-api-version=v3. The documentation itself warns that features may still change or be removed. For production the rule is therefore: stay on apiVersion: v2 and only watch v3 for now.

The plugin system was also reworked (plugin apiVersion v1) and brings an optional WebAssembly runtime for more security and OCI distribution. Existing plugins keep working, though; the move to WebAssembly is optional, not mandatory.

The low-risk migration path

Because no automatic conversion is needed, the recommended switch follows a simple test-first pattern:

1. Install the Helm 4 CLI in parallel and use it first in non-production environments. Both versions see the same cluster state.
2. Test existing charts and releases - helm template, helm upgrade --dry-run and a real upgrade in staging surface any snags early.
3. Update RBAC: wherever --wait is used, add the watch verb and verify beforehand with kubectl auth can-i watch ....
4. Adjust CI/CD scripts: replace renamed flags, switch helm registry login to domain-only, remove --create-pods.
5. Rewire post-renderers as plugins if used.
6. Test registry and OCI workflows (login, push, pull with the new behavior).
7. Check your own SDK usage and move to the import path helm.sh/helm/v4.

Only after these steps in non-production does the production rollout follow - ideally through the same GitOps and platform engineering pipeline that rolls out the applications.

Four stumbling blocks

Finally, the points where migrations tend to get stuck:

• --wait breaks immediately without watch RBAC. The most common mistake right after switching - fix RBAC first.
• Post-renderer pipelines break silently. Executable paths to --post-renderer no longer work; rewire as a plugin, or GitOps renderings fail.
• CI/CD breaks at login and flags. Path components in registry login and scripts with --atomic/--force need adjusting.
• The apply-method split surprises. New releases use server-side apply, migrated Helm 3 releases stay on client-side apply. Plan for this mixed behavior and possible field-ownership conflicts.

Helm 4 is therefore a controllable but not trivial switch. Teams that tackle it early and test it have plenty of buffer until early 2027 - and avoid the pressure of migrating in a rush just before security support ends.

The other big lifecycle change in 2026 concerns the cluster network: migrating from ingress-nginx to the Gateway API. And whether Kubernetes is the right path for your application at all is answered in Do we need Kubernetes?