Helm commands

2026-11-11

The exact helm command and flag for each task, for Helm 4 (v4.3), with the Helm 3 spelling where a flag was renamed. Charts, templating and what changed in Helm 4 are explained in Helm; the objects a release creates are inspected with kubectl commands.

Install the CLI

Platform	Install
macOS, Linux with Homebrew	`brew install helm`
Windows	`winget install Helm.Helm`, `choco install kubernetes-helm` or `scoop install helm`
Fedora	`sudo dnf install helm`
Snap	`sudo snap install helm --classic`
Debian, Ubuntu	an apt repository (setup steps in the install guide), then `sudo apt-get install helm`
Any	the installer script or a binary from the GitHub releases page

Only the script and the release binaries come from the Helm project; the package managers are community-maintained and can lag a release behind.

u=https://raw.githubusercontent.com/helm/helm/main/scripts
curl -fsSL -o get_helm.sh "$u/get-helm-4"
chmod 700 get_helm.sh && ./get_helm.sh
helm version --short

Command	Does
`helm version`	client version, Git commit, Go version; `--short` for just `v4.3.x`
`helm env`	every `HELM_*` setting in effect; `helm env HELM_CACHE_HOME` for one
`helm completion bash`, `zsh`, `fish`, `powershell`	shell completion script, e.g. `source <(helm completion zsh)`
`helm help upgrade`, `helm upgrade -h`	a command's flags

Renamed in Helm 4

Scripts written for Helm 3 mostly keep working: old flag names print a deprecation warning.

Helm 3	Helm 4
`--atomic`	`--rollback-on-failure`
`--force`	`--force-replace`
`--wait` (yes or no)	`--wait` means `--wait=watcher`; `hookOnly` (the default) and `legacy` are the other strategies
bare `--dry-run` (client)	`--dry-run=client`, `server` or `none`; the bare form still works but is deprecated
`helm list` showed deployed and failed; `-a` for all	every status by default; no `-a`
`helm status --show-resources`	resources are listed by default
`helm template --validate`	`helm template --dry-run=server`
`helm registry login` with a URL	host name only: `helm registry login ghcr.io`
`--post-renderer ./script.sh`	`--post-renderer NAME` of a post-renderer plugin
`helm plugin install https://github.com/…`	tarballs are signature-checked; Git sources need `--verify=false`

Global flags and environment

Flag	Environment variable	Does
`-n web`	`HELM_NAMESPACE`	release namespace (default: the kubeconfig context's)
`--kube-context prod`	`HELM_KUBECONTEXT`	kubeconfig context
`--kubeconfig f`	`KUBECONFIG`	kubeconfig file
`--kube-as-user`, `--kube-as-group`	`HELM_KUBEASUSER`, `HELM_KUBEASGROUPS`	impersonation
`--kube-token`, `--kube-apiserver`	`HELM_KUBETOKEN`, `HELM_KUBEAPISERVER`	connect without a kubeconfig
`--debug`	`HELM_DEBUG`	verbose output
`--burst-limit`, `--qps`	`HELM_BURST_LIMIT`, `HELM_QPS`	client throttling, for clusters with many CRDs
	`HELM_DRIVER`	where releases are stored: `secret` (default), `configmap`, `memory`, `sql`
	`HELM_MAX_HISTORY`	default for `--history-max` (10)
	`HELM_NO_PLUGINS=1`	disable plugins
	`NO_COLOR`	no colored output
	`SOURCE_DATE_EPOCH`	fixed timestamps for reproducible `helm package` archives

OS	Cache (`HELM_CACHE_HOME`)	Config (`HELM_CONFIG_HOME`)	Data (`HELM_DATA_HOME`)
Linux	`~/.cache/helm`	`~/.config/helm`	`~/.local/share/helm`
macOS	`~/Library/Caches/helm`	`~/Library/Preferences/helm`	`~/Library/helm`
Windows	`%TEMP%\helm`	`%APPDATA%\helm`	`%APPDATA%\helm`

HELM_*_HOME wins, then the XDG variables, then the defaults above. Inside them: repositories.yaml and registry/config.json (credentials) live in config, plugins and starters in data, repository indexes in cache/repository.

Repositories and search

Command	Does
`helm repo add grafana https://grafana.github.io/helm-charts`	register an HTTP chart repository
`helm repo add acme https://charts.acme.dev --username ci --password-stdin`	a private one
`helm repo add … --force-update`	overwrite an existing entry with the same name
`helm repo update`	download fresh indexes for all repos; `helm repo update grafana` for one
`helm repo list`	names and URLs; `-o json`
`helm repo remove grafana`	forget a repo
`helm repo index ./public --url https://charts.acme.dev`	write `index.yaml` for hosting your own; `--merge old.yaml`
`helm search repo loki`	charts in added repos (from the local index, so `repo update` first)
`helm search repo grafana/loki --versions`	every version (`-l`)
`helm search repo grafana/loki --version '^6.0'`	versions matching a range
`helm search repo -r 'grafana/(loki\|tempo)'`	regular expression
`helm search repo … --devel`	include pre-releases
`helm search hub prometheus`	Artifact Hub; `--list-repo-url` adds the repo URL to add
`helm install loki loki --repo https://grafana.github.io/helm-charts`	use a repo without adding it

OCI registries have no repo add and no search: use the full oci:// reference (see Chart authoring).

Install and upgrade

helm install api ./api -n web --create-namespace
helm upgrade api ./api -n web -f values/prod.yaml
# install or upgrade in one idempotent command (CI)
helm upgrade --install api ./api -n web \
  --create-namespace -f values/prod.yaml

Chart reference	Means
`./api`	an unpacked chart directory
`./api-1.2.0.tgz`	a packaged chart
`grafana/loki`	`repo/chart` from an added repository
`loki --repo https://grafana.github.io/helm-charts`	repository URL, no `repo add` needed
`https://charts.acme.dev/api-1.2.0.tgz`	an absolute URL
`oci://ghcr.io/acme/charts/api`	an OCI registry; `--version` picks the tag
`oci://ghcr.io/acme/charts/api@sha256:…`	pinned by digest

Release names are at most 53 characters of lowercase letters, digits, - and ., starting and ending with a letter or digit. helm install ./api --generate-name (-g) picks one; --name-template builds one.

Flags

filter

Flag	Does
`-n web`, `--create-namespace`	release namespace; create it if missing (on `upgrade` only with `--install`)
`-i`, `--install`	`upgrade` installs when the release doesn't exist yet
`--version 1.2.0`	chart version, or a range such as `~1.2.0` or `^1.2`; latest stable if omitted
`--devel`	allow pre-release chart versions
`--dependency-update`	fetch missing `dependencies` of a local chart first
`--verify`	check the chart's `.prov` signature (`--keyring`)
`-f values.yaml`	values file; repeatable, later files win; also a URL or `-` for stdin
`--set`, `--set-string`, `--set-json`, `--set-file`, `--set-literal`	single values (syntax below)
`--wait`	wait until every resource is ready (`watcher` strategy, kstatus)
`--wait=hookOnly`	the default: wait for hooks only
`--wait=legacy`	Helm 3's readiness logic
`--wait-for-jobs`	with `--wait`, also wait for Jobs to complete
`--timeout 10m`	per Kubernetes operation (hook Jobs, the wait); default `5m0s`
`--rollback-on-failure`	Helm 3 `--atomic`: a failed upgrade rolls back, a failed install is uninstalled; turns on `--wait=watcher`
`--cleanup-on-fail`	`upgrade`: delete objects this attempt created if it fails
`--server-side=false`	`install`: client-side apply instead of the default server-side apply
`--server-side=true\|false\|auto`	`upgrade`, `rollback`: default `auto` keeps the release's previous method
`--force-conflicts`	with server-side apply, take fields owned by another manager
`--force-replace`	Helm 3 `--force`: replace objects with a full update (PUT) instead of a patch; client-side apply only, so add `--server-side=false`
`--take-ownership`	adopt existing objects that lack Helm's ownership annotations
`--skip-crds`	don't install the chart's `crds/`
`--no-hooks`	skip hooks
`--skip-schema-validation`	ignore `values.schema.json`
`--disable-openapi-validation`	don't check rendered objects against the cluster's schemas
`--dry-run=client`	render and print, no cluster contact
`--dry-run=server`	render with cluster access (`lookup`, real capabilities), store nothing
`--hide-secret`	with `--dry-run`, leave Secret contents out of the output
`-o json`, `-o yaml`	machine-readable result
`--description "deploy 4f2c1a"`	shown in `helm history`
`-l team=payments`	labels on the release record (`--labels`); filter with `helm list -l`
`--history-max 20`	revisions kept per release (default 10, `0` = unlimited)
`--post-renderer NAME`	pipe rendered YAML through a post-renderer plugin; `--post-renderer-args`
`--enable-dns`	allow DNS lookups in templates
`--hide-notes`	don't print NOTES
`--replace`	`install`: reuse the name of a release uninstalled with `--keep-history` (unsafe in production)
`--username`, `--password`, `--ca-file`, `--plain-http`, `--insecure-skip-tls-verify`	chart download credentials and TLS

Value flags

You want	Flag	Result
a nested key	`--set image.tag=1.4.2`	`image: {tag: "1.4.2"}`
several keys	`--set replicaCount=3,service.port=80`	or repeat `--set`
a list	`--set 'args={serve,--port=3000}'`	`args: [serve, --port=3000]`
one list item	`--set 'hosts[0]=api.acme.dev'`	indexes from 0
fields of a list item	`--set 'env[0].name=MODE,env[0].value=prod'`	`env: [{name: MODE, value: prod}]`
a comma in a value	`--set 'ips=10.0.0.1\,10.0.0.2'`	the string `10.0.0.1,10.0.0.2`
a dot in a key	`--set 'podAnnotations.prometheus\.io/scrape=true'`	key `prometheus.io/scrape`
delete a default	`--set ingress.annotations=null`	the key is removed
a number kept as text	`--set-string image.tag=110`	`"110"`, not the integer `110`
structured data	`--set-json 'tolerations=[{"key":"gpu","operator":"Exists"}]'`	lists and maps as JSON
a file's content	`--set-file config=./app.toml`	the whole file as one string
no parsing at all	`--set-literal 'password=a,b=c\d'`	commas, `=` and `\` kept
values from a pipe	`sops -d secrets.yaml \| helm upgrade api ./api -f -`	`-f -` reads stdin

--set turns true, false, null and plain integers into typed values; everything else, 1.10 included, stays a string. Single-quote the argument so the shell leaves {}, [] and \ alone. Lowest to highest precedence: chart defaults, -f files left to right, --set-json, --set, --set-string, --set-file, --set-literal.

Each key comes from the highest layer that sets it; keys nobody overrides keep the chart's default.

Values on upgrade

Flags	Values used
`-f` or `--set` given	new chart defaults plus exactly what this command passes
no value flags at all	new chart defaults plus the last release's user-supplied values
`--reuse-values`	last release's values, old chart defaults included, plus this command's; new chart defaults are ignored
`--reset-then-reuse-values`	new chart defaults, then the last release's user-supplied values, then this command's
`--reset-values`	new chart defaults plus this command's only, even with no value flags

Passing the same -f values/prod.yaml on every upgrade is the only form that is reproducible from Git; see Values and overrides.

Inspecting releases

filter

Command	Shows
`helm list`	releases in the current namespace, any status, alphabetical
`helm list -A`	every namespace
`helm list --failed`, `--pending`, `--deployed`, `--superseded`, `--uninstalled`, `--uninstalling`	only those statuses (combinable)
`helm list -q`	names only
`helm list -f '^api'`	release names matching a regular expression
`helm list -l team=payments`	by release labels
`helm list -d -r`	newest first
`helm list -o json`	for scripts; up to 256 releases unless `-m`
`helm status api`	status, revision, resources and NOTES
`helm status api --revision 6 -o yaml`	an older revision, machine-readable
`helm history api`	every revision: status, chart, app version, description
`helm history api --max 5 -o json`	the last five, for scripts
`helm get values api`	the values you supplied
`helm get values api -a`	all computed values, chart defaults included
`helm get values api --revision 6 -o json`	as of a revision
`helm get manifest api`	the rendered objects as applied (hooks excluded)
`helm get hooks api`	rendered hook objects
`helm get notes api`	NOTES output
`helm get metadata api`	chart, versions, namespace, status, deploy time
`helm get all api`	all of the above; `--template '{{.Release.Name}}'` to pick fields
`helm show values grafana/loki --version 6.40.0`	a chart's defaults, without installing
`helm show values grafana/loki --jsonpath '{.loki.storage}'`	one subtree
`helm show chart`, `show readme`, `show crds`, `show all`	`Chart.yaml`, README, CRDs, everything

show takes any chart reference (directory, .tgz, repo/chart, oci://); get takes a release name.

Status	Means
`deployed`	the current, successful revision
`superseded`	an older revision that was deployed and has been replaced
`failed`	the install, upgrade or rollback errored or timed out
`pending-install`, `pending-upgrade`, `pending-rollback`	in progress, or the process died mid-way
`uninstalling`, `uninstalled`	being removed; removed with `--keep-history`

1/4

helm install creates revision 1, status deployed: Install complete.

Rollback and uninstall

filter

Command	Does
`helm rollback api`	to the revision before the latest one (current minus 1, even if that one failed)
`helm rollback api 7`	to revision 7, recorded as a new revision "Rollback to 7"
`--wait`, `--wait-for-jobs`, `--timeout 10m`	wait for readiness, as on upgrade
`--cleanup-on-fail`	delete objects the failed rollback created
`--force-replace`	Helm 3 `--force`
`--server-side`, `--force-conflicts`	apply method, as on upgrade
`--no-hooks`	skip `pre-rollback`, `post-rollback`
`--dry-run=client`	simulate
`helm uninstall api -n web`	delete the release's objects and its history
`helm uninstall api web worker`	several releases
`--keep-history`	keep the records (status `uninstalled`); `helm rollback api N` brings it back
`--wait`	return only when the objects are gone
`--cascade=foreground`, `orphan`	deletion propagation; default `background`
`--no-hooks`	skip `pre-delete`, `post-delete`
`--ignore-not-found`	no error for a missing release
`--dry-run`	simulate the uninstall

uninstall leaves behind objects annotated helm.sh/resource-policy: keep, hook objects without a delete policy, PVCs created from StatefulSet volumeClaimTemplates, and CRDs from the chart's crds/ directory (Helm never deletes those).

Rendering, linting and tests

`helm template`	Does
`helm template api ./api -f values/prod.yaml`	render to stdout; no cluster needed
`-n web`	sets `.Release.Namespace`
`-s templates/deployment.yaml`	only that template (`--show-only`, repeatable)
`--output-dir out/`	one file per template; `--release-name` adds the release to the path
`--include-crds`, `--skip-tests`	include `crds/`; leave out test hooks
`--is-upgrade`	render as an upgrade (`.Release.IsUpgrade`)
`--kube-version 1.37.0`	`.Capabilities.KubeVersion`
`-a gateway.networking.k8s.io/v1`	add to `.Capabilities.APIVersions` (`--api-versions`, repeatable)
`--dry-run=server`	use the cluster: real capabilities and working `lookup`
`--debug`	on a YAML error, print the broken output

Helm renders on your machine. The cluster only sees the finished manifests, and the release record keeps a copy of each revision.

Command	Does
`helm lint ./api`	chart structure, templates, schema, values
`helm lint ./api --strict -f values/prod.yaml`	warnings fail; lint with real values
`helm lint ./api --with-subcharts --kube-version 1.37.0`	include dependencies; check deprecations for a version
`helm lint ./api --quiet`	warnings and errors only
`helm test api -n web`	run the chart's `helm.sh/hook: test` Pods
`helm test api --logs`	print their logs
`helm test api --filter name=api-test-db`	some tests; `!name=x` excludes

Chart authoring

filter

Command	Does
`helm create api`	scaffold a chart
`helm create api -p web-starter`	from a starter in `$HELM_DATA_HOME/starters`, or an absolute path (`--starter`)
`helm dependency list ./api`	each dependency and its state: `ok`, `missing`, `wrong version`, `unpacked`
`helm dependency update ./api`	resolve version ranges, download into `charts/`, write `Chart.lock`
`helm dependency build ./api`	rebuild `charts/` exactly from `Chart.lock` (CI)
`helm dependency update ./api --skip-refresh`	don't refresh repository indexes first
`helm package ./api`	build `api-<version>.tgz`
`helm package ./api --version 1.2.0 --app-version 1.4.2 -d dist/`	override versions, choose the output directory
`helm package ./api -u`	run `dependency update` first
`helm pull grafana/loki --version 6.40.0`	download the `.tgz`
`helm pull grafana/loki --untar --untardir vendor/`	download and unpack
`helm pull oci://ghcr.io/acme/charts/api --version 1.2.0`	from a registry
`helm registry login ghcr.io -u acme --password-stdin`	store registry credentials
`helm registry logout ghcr.io`	remove them
`helm push api-1.2.0.tgz oci://ghcr.io/acme/charts`	publish as `ghcr.io/acme/charts/api:1.2.0`; prints the digest
`helm push … --plain-http`	a registry without TLS, such as a local test registry

# release a chart to an OCI registry
helm lint ./api --strict
helm dependency build ./api
helm package ./api --version 1.2.0 --app-version 1.4.2
echo "$GHCR_TOKEN" | helm registry login ghcr.io \
  -u "$GH_USER" --password-stdin
helm push api-1.2.0.tgz oci://ghcr.io/acme/charts

Signing and verification

A provenance file (api-1.2.0.tgz.prov) holds the chart's Chart.yaml, its SHA-256 and a PGP signature. Helm reads only the legacy GnuPG keyring format, so export keys first.

gpg --export-secret-keys > ~/.gnupg/secring.gpg
gpg --export > ~/.gnupg/pubring.gpg
helm package ./api --sign --key 'Acme Charts' \
  --keyring ~/.gnupg/secring.gpg
helm verify api-1.2.0.tgz --keyring ~/.gnupg/pubring.gpg
helm install api ./api-1.2.0.tgz --verify \
  --keyring ~/.gnupg/pubring.gpg

Command	Does
`helm package --sign --key NAME`	write the `.prov` next to the `.tgz`; `--passphrase-file` for CI
`helm verify CHART.tgz`	check signature and hash
`helm pull … --prov`	also download the `.prov`
`helm pull … --verify`, `helm install … --verify`	refuse an unsigned or tampered chart
`helm dependency update --verify`	verify dependencies too

Charts in OCI registries are often signed with Sigstore cosign instead, as any OCI artifact.

Plugins

Command	Does
`helm plugin list`	installed plugins with type and signature status; `--type cli/v1` (or `getter/v1`, `postrenderer/v1`) filters
`helm plugin install URL.tgz`	install from a tarball; its `.prov` signature is checked by default
`helm plugin install ./my-plugin`	a local directory, no signature needed
`helm plugin install https://github.com/org/repo --verify=false`	a Git source, which can't be verified
`helm plugin install … --version 3.9.0`	a version constraint
`helm plugin update diff`	update
`helm plugin uninstall diff`	remove
`helm plugin verify ./plugin.tgz`	check a plugin archive's signature
`helm plugin package ./my-plugin`	build a signed plugin archive (authors)

Plugin	Use it for	Example
helm-diff	preview what an upgrade, rollback or revision change does	`helm diff upgrade api ./api -f values/prod.yaml`
helm-secrets	SOPS-encrypted values files	`helm upgrade api ./api -f secrets://values/secrets.yaml`
helm-unittest	unit tests for templates in `tests/*_test.yaml`	`helm unittest ./api`
helm-mapkubeapis	rewrite removed API versions inside release records so upgrades work again	`helm mapkubeapis api -n web`

The Helm sheet shows a full helm-diff install with its signing key.

Quick lookup

filter

I want to…	Command
find a chart	`helm search hub loki` or `helm search repo loki`
see a chart's default values	`helm show values grafana/loki > loki-defaults.yaml`
list chart versions	`helm search repo grafana/loki --versions`
install or upgrade	`helm upgrade --install api ./api -n web --create-namespace -f values/prod.yaml`
pin a chart version	add `--version 1.2.0`
roll back automatically on failure	add `--rollback-on-failure --timeout 10m` (Helm 3: `--atomic`)
wait until everything is ready	add `--wait`
preview without applying	`helm upgrade api ./api --dry-run=server --hide-secret` or `helm diff upgrade …`
render YAML locally	`helm template api ./api -f values/prod.yaml`
render one file	`helm template api ./api -s templates/service.yaml`
list releases everywhere	`helm list -A`
find failed or stuck releases	`helm list -A --failed --pending`
see what is deployed	`helm get manifest api`
see the values in use	`helm get values api` (`-a` for all)
see revision history	`helm history api`
roll back	`helm rollback api 7`
uninstall but keep history	`helm uninstall api --keep-history`
adopt existing objects	`helm upgrade --install api ./api --take-ownership`
change one value, keep the rest	`helm upgrade api ./api --reuse-values --set replicaCount=4`
upgrade the chart, keep my overrides	`helm upgrade loki grafana/loki --reset-then-reuse-values`
package a chart	`helm package ./api`
push to a registry	`helm push api-1.2.0.tgz oci://ghcr.io/acme/charts`
install from a registry	`helm install api oci://ghcr.io/acme/charts/api --version 1.2.0`
vendor a chart	`helm pull grafana/loki --version 6.40.0 --untar`
refresh dependencies	`helm dependency update ./api`
check a chart	`helm lint ./api --strict`
run chart tests	`helm test api --logs`
find where Helm keeps files	`helm env`
store releases in ConfigMaps	`HELM_DRIVER=configmap helm …`
see release records directly	`kubectl get secret -n web -l owner=helm,name=api`

References

Helm commands (opens in a new tab): the generated reference for every command and flag
helm install (opens in a new tab), helm upgrade (opens in a new tab), helm template (opens in a new tab), helm list (opens in a new tab): the most-used pages
Installing Helm (opens in a new tab): script, binaries and package managers
Using Helm (opens in a new tab): repos, releases and the --set format
Helm cheat sheet (opens in a new tab): the official one-page summary
Helm 4 overview (opens in a new tab): renamed flags and changed defaults
OCI registries (opens in a new tab): login, push, pull and install
Provenance and integrity (opens in a new tab): signing and verifying charts
Plugins (opens in a new tab): plugin types, installing and writing them
Debugging templates (opens in a new tab): --debug, --dry-run and template
Deprecated Kubernetes APIs (opens in a new tab): why releases break after cluster upgrades
helm-diff (opens in a new tab), helm-secrets (opens in a new tab), helm-unittest (opens in a new tab), helm-mapkubeapis (opens in a new tab): the plugins above
Artifact Hub (opens in a new tab): find public charts and their values