On this page

Helm Cheat Sheet

Quick reference for Helm, the package manager for Kubernetes. Covers chart structure, templating, lifecycle commands, hooks, OCI registries and common patterns.

Versions: Helm 4 (released November 2025, 4.3.x current) is the current major version; Helm 3 (3.22.x) still gets fixes. Commands below work on both unless marked. What changed in Helm 4 for CLI users:

Helm 3Helm 4
--atomic--rollback-on-failure (old name still works, with a deprecation warning)
--force--force-replace (old name deprecated)
Client-side apply (three-way merge)Server-side apply for new releases; releases created by Helm 3 keep client-side apply unless you pass --server-side
helm registry login https://host/pathhelm registry login host (domain only)
--post-renderer ./script.sh--post-renderer takes a plugin name; wrap scripts as post-renderer plugins
—Install by digest: oci://reg/app@sha256:...

The examples use bitnami/... charts as familiar names. Since 2025 Bitnami's free catalog no longer receives regular image updates (most images moved to the paid Bitnami Secure Images, old ones to bitnamilegacy), so check what a chart pulls before using it in production.

Related: Kubernetes Cheat Sheet | kubectl Advanced


Repository Management

CommandDescription
helm repo add bitnami https://charts.bitnami.com/bitnamiAdd a chart repository
helm repo add stable https://charts.helm.sh/stableAdd legacy stable repo (archived since 2020, no updates)
helm repo add myrepo https://charts.example.com --username u --password-stdinAdd a private HTTP repo
helm repo updateUpdate repo index
helm repo listList configured repos
helm repo remove bitnamiRemove a repo
helm search repo nginxSearch repos for a chart
helm search repo nginx --versionsShow all available versions
helm search hub wordpressSearch Artifact Hub
helm search repo nginx --develInclude pre-release versions
helm pull bitnami/nginx --untarDownload and unpack a chart to inspect it

OCI registries don't use helm repo add; you reference them directly with oci:// URLs (see OCI Registries).


Chart Lifecycle

Install

CommandDescription
helm install my-release bitnami/nginxInstall a chart
helm install my-release bitnami/nginx -n productionInstall in specific namespace
helm install my-release bitnami/nginx -f values.yamlInstall with custom values
helm install my-release bitnami/nginx --set replicaCount=3Install with inline overrides
helm install my-release bitnami/nginx --set-string image.tag="1.25"Force value as string
helm install my-release bitnami/nginx --version 15.0.0Install specific chart version
helm install my-release ./my-chartInstall from local chart directory
helm install my-release my-chart.tgzInstall from local archive
helm install my-release bitnami/nginx --dry-run --debugDry run (render templates only)
helm install my-release bitnami/nginx --dry-run=serverDry run that also validates against the cluster (and makes lookup work)
helm install my-release bitnami/nginx --wait --timeout 5mWait for resources to be ready (default timeout 5m)
helm install my-release bitnami/nginx --create-namespace -n new-nsCreate namespace if missing
helm install bitnami/nginx --generate-nameLet Helm pick a release name
helm install my-release bitnami/nginx --set-file config=./app.confSet a value from a file's contents
helm install my-release bitnami/nginx --set-json 'resources={"limits":{"cpu":"500m"}}'Set a structured value as JSON
helm install my-release bitnami/nginx --take-ownershipAdopt existing resources not created by Helm (3.17+)

--set Syntax

SyntaxResult in values
--set a.b=1a: {b: 1}
--set a=1,b=2Two values
--set list={x,y}list: [x, y]
--set servers[0].port=80Index into a list
--set name=a\,bEscape a comma
--set nodeSelector."kubernetes\.io/os"=linuxKey containing dots
--set key=nullRemove a default key

Precedence (later wins): chart values.yaml → parent chart values → -f files in order → --set/--set-string/--set-file/--set-json.

Upgrade

CommandDescription
helm upgrade my-release bitnami/nginxUpgrade a release
helm upgrade my-release bitnami/nginx -f values-prod.yamlUpgrade with new values
helm upgrade my-release bitnami/nginx --reuse-values --set replicas=5Keep existing values, override one
helm upgrade --install my-release bitnami/nginxInstall if not exists, upgrade if it does
helm upgrade my-release bitnami/nginx --atomicAuto-rollback on failure (Helm 4: --rollback-on-failure)
helm upgrade my-release bitnami/nginx --forceForce resource update by delete-and-recreate (Helm 4: --force-replace)
helm upgrade my-release bitnami/nginx --reset-then-reuse-valuesStart from chart defaults, re-apply previous user values, then your overrides (3.14+)
helm upgrade my-release bitnami/nginx --server-sideUse server-side apply (Helm 4)
helm upgrade my-release bitnami/nginx --history-max 10Keep at most 10 revisions (default 10; 0 = unlimited)
helm upgrade my-release bitnami/nginx --cleanup-on-failDelete resources created by a failed upgrade

Typical CI deploy:

helm upgrade --install api oci://ghcr.io/myorg/charts/api --version 1.4.2 \
  -n prod --create-namespace -f values-prod.yaml \
  --set image.tag="$GIT_SHA" --wait --timeout 10m --atomic

WARNING

--reuse-values merges with existing values. Without it, all values reset to chart defaults plus your overrides. This catches people off guard.

Rollback

CommandDescription
helm rollback my-releaseRollback to previous revision
helm rollback my-release 3Rollback to specific revision
helm rollback my-release 3 --waitRollback and wait for readiness

Uninstall

CommandDescription
helm uninstall my-releaseDelete a release
helm uninstall my-release -n productionDelete from specific namespace
helm uninstall my-release --keep-historyDelete but keep history

Inspect & Debug

CommandDescription
helm listList installed releases in current namespace
helm list -AList releases across all namespaces
helm list --pendingShow pending releases
helm status my-releaseShow release status
helm history my-releaseShow release revision history
helm get values my-releaseShow user-supplied values
helm get values my-release --allShow all computed values
helm get manifest my-releaseShow rendered Kubernetes manifests
helm get notes my-releaseShow release notes
helm get hooks my-releaseShow release hooks
helm show chart bitnami/nginxShow chart metadata
helm show values bitnami/nginxShow default values.yaml
helm show readme bitnami/nginxShow chart README
helm template my-release bitnami/nginx -f values.yamlRender templates locally (no install)
helm template my-release ./my-chart -s templates/deployment.yamlRender a single template
helm template my-release ./my-chart --api-versions monitoring.coreos.com/v1 --kube-version 1.34Fake cluster capabilities while rendering offline
helm get all my-release --revision 3Everything about one revision
helm list -a / helm list --failedAll releases incl. failed/pending / only failed
helm envHelm's paths and settings (HELM_NAMESPACE, cache, config dirs)
helm diff upgrade my-release bitnami/nginx -f values.yamlPreview changes before upgrading (helm-diff plugin)

Release stuck in "another operation is in progress"

A crashed upgrade can leave the release in pending-upgrade/pending-install. Check helm history my-release, then helm rollback my-release <last-good-revision>. Release state lives in Secrets named sh.helm.release.v1.<name>.v<revision> in the release namespace.


Chart Structure

my-chart/
├── Chart.yaml          # Chart metadata (name, version, dependencies)
├── Chart.lock          # Locked dependency versions
├── values.yaml         # Default configuration values
├── values.schema.json  # JSON Schema for values validation
├── templates/
│   ├── _helpers.tpl    # Template helpers and partials
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── configmap.yaml
│   ├── hpa.yaml
│   ├── serviceaccount.yaml
│   ├── NOTES.txt       # Post-install instructions
│   └── tests/
│       └── test-connection.yaml
├── charts/             # Dependency chart archives
├── crds/               # Custom Resource Definitions
└── .helmignore         # Files to exclude from packaging

Chart.yaml

apiVersion: v2
name: my-app
description: My application Helm chart
type: application          # application or library
version: 1.2.0             # Chart version (SemVer)
appVersion: "3.5.1"        # Application version
dependencies:
  - name: postgresql
    version: "12.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
  - name: redis
    version: "17.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled
  - name: common
    version: "~2.2.0"
    repository: "oci://registry-1.docker.io/bitnamicharts"   # OCI dependency: no `helm repo add` needed
    alias: shared                                           # refer to its values as .Values.shared
kubeVersion: ">=1.29.0-0"  # refuse to install on older clusters

version is the chart's own SemVer and must be bumped for every chart change; appVersion is informational (often used as the default image tag).


Templating Essentials

Built-in Objects

ObjectDescription
.Release.NameRelease name
.Release.NamespaceRelease namespace
.Release.IsUpgradeTrue if upgrade/rollback
.Release.IsInstallTrue if install
.Release.RevisionRevision number
.Chart.NameChart name
.Chart.VersionChart version
.Chart.AppVersionApp version
.ValuesValues from values.yaml and overrides
.Capabilities.KubeVersionKubernetes version
.Capabilities.APIVersions.Has "networking.k8s.io/v1/Ingress"Check whether the cluster serves an API
.Release.ServiceAlways Helm
.FilesNon-template files in the chart (.Files.Get "conf/app.ini")
.Template.NameCurrent template file path

Common Template Functions

# String functions
name: {{ .Values.name | upper }}
name: {{ .Values.name | lower }}
name: {{ .Values.name | title }}
name: {{ .Values.name | quote }}
name: {{ .Values.name | trim }}
name: {{ .Values.name | replace "old" "new" }}
name: {{ printf "%s-%s" .Release.Name .Chart.Name }}

# Default values
image: {{ .Values.image | default "nginx:latest" }}

# Required values (fails if missing)
password: {{ required "password is required" .Values.password }}

# Conditionals
{{- if .Values.ingress.enabled }}
  # ingress resources
{{- end }}

# Ternary
replicas: {{ ternary 3 1 .Values.production }}

# Loops
{{- range .Values.env }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

# With (change scope)
{{- with .Values.nodeSelector }}
nodeSelector:
  {{- toYaml . | nindent 2 }}
{{- end }}

# Inside range/with, "." is the item: use $ for the root context
{{- range .Values.hosts }}
- host: {{ . }}
  release: {{ $.Release.Name }}
{{- end }}

# Range over a map with key/value
{{- range $key, $val := .Values.extraEnv }}
- name: {{ $key }}
  value: {{ $val | quote }}
{{- end }}

# Variables
{{- $fullName := include "my-app.fullname" . }}

# Whitespace control: {{- trims before, -}} trims after

# Logic and comparison
{{- if and .Values.ingress.enabled (eq .Values.env "prod") }}
{{- if not (empty .Values.extraArgs) }}
{{- if hasKey .Values "legacy" }}

# Restart pods when a ConfigMap changes
annotations:
  checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}

# Embed files from the chart
data:
  {{- (.Files.Glob "config/*").AsConfig | nindent 2 }}
  app.ini: |-
    {{- .Files.Get "files/app.ini" | nindent 4 }}

# Base64 for Secrets
password: {{ .Values.password | b64enc | quote }}

# Read a live object from the cluster (empty under helm template / client dry-run)
{{- $existing := lookup "v1" "Secret" .Release.Namespace "my-secret" }}

# Fail rendering with a message
{{- fail "ingress.host is required when ingress is enabled" }}

# Render a value that itself contains template syntax
{{ tpl .Values.customLabel . }}
FunctionExample
toYaml / toJson / fromYamltoYaml .Values.resources | nindent 12
indent vs nindentnindent adds a newline first, so it works after key:
defaultNote default treats false and 0 as empty: use ternary or hasKey for booleans
coalesceFirst non-empty value
list, dict, merge, getBuild and combine collections
semverComparesemverCompare ">=1.30-0" .Capabilities.KubeVersion.Version
randAlphaNumRandom string (changes every upgrade unless combined with lookup)

Helper Templates (_helpers.tpl)

{{/* Generate standard labels */}}
{{- define "my-app.labels" -}}
helm.sh/chart: {{ include "my-app.chart" . }}
app.kubernetes.io/name: {{ include "my-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/* Generate a fullname with release */}}
{{- define "my-app.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/* Usage in templates */}}
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}

Hooks

Hooks run at specific points in the release lifecycle.

Annotation ValueWhen It Runs
pre-installBefore any resources are installed
post-installAfter all resources are installed
pre-upgradeBefore any resources are upgraded
post-upgradeAfter all resources are upgraded
pre-deleteBefore any resources are deleted
post-deleteAfter all resources are deleted
pre-rollbackBefore a rollback
post-rollbackAfter a rollback
testWhen helm test is run

Hook Example — Database Migration

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "my-app.fullname" . }}-migrate
  annotations:
    "helm.sh/hook": pre-upgrade
    "helm.sh/hook-weight": "0"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
          command: ["npm", "run", "migrate"]
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: {{ include "my-app.fullname" . }}-secrets
                  key: database-url

Hook Delete Policies

PolicyDescription
hook-succeededDelete after hook succeeds
hook-failedDelete after hook fails
before-hook-creationDelete previous hook before launching new one (the default when no policy is set)

Lower helm.sh/hook-weight runs first (weights are strings, can be negative). Helm waits for hook Jobs/Pods to complete before continuing; a failed hook fails the release. Use "helm.sh/resource-policy": keep on a normal resource (e.g. a PVC) to stop helm uninstall from deleting it.


Dependencies

# Update dependencies (downloads to charts/)
helm dependency update ./my-chart

# List dependencies
helm dependency list ./my-chart

# Build (download the exact versions pinned in Chart.lock)
helm dependency build ./my-chart

update resolves the ranges in Chart.yaml and rewrites Chart.lock; build reproduces what Chart.lock says (use it in CI). Parent charts set subchart values under the subchart's name (or alias), and global: values are visible to every subchart as .Values.global.

Conditional Dependencies in values.yaml

# values.yaml
postgresql:
  enabled: true
  auth:
    postgresPassword: "secret"
    database: "myapp"

redis:
  enabled: false

Chart Development

# Create a new chart scaffold
helm create my-chart

# Lint a chart for errors
helm lint ./my-chart

# Lint with specific values
helm lint ./my-chart -f values-prod.yaml

# Package a chart
helm package ./my-chart

# Package with specific version
helm package ./my-chart --version 2.0.0

# Push to OCI registry
helm push my-chart-2.0.0.tgz oci://registry.example.com/charts

# Template (render locally without install)
helm template my-release ./my-chart -f values.yaml --debug

# Run chart tests
helm test my-release

# Validate rendered manifests against Kubernetes schemas (third-party)
helm template my-release ./my-chart | kubeconform -strict -summary

# Unit-test templates (helm-unittest plugin)
helm unittest ./my-chart

values.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["image"],
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 1 },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": { "tag": { "type": "string" } }
    }
  }
}

helm install, upgrade, lint and template all validate values against this file, so typos like replicas: "3" fail early.

Plugins

CommandDescription
helm plugin install https://github.com/databus23/helm-diffInstall a plugin
helm plugin listList plugins
helm plugin update diffUpdate a plugin
helm plugin uninstall diffRemove a plugin

TIP

Always run helm lint and helm template before pushing chart changes. Catch YAML errors locally, not in production.


OCI Registry Support

# Login to OCI registry (Helm 4: domain only, no https:// or path)
helm registry login registry.example.com
echo "$TOKEN" | helm registry login ghcr.io -u USER --password-stdin

# Push chart to OCI
helm push my-chart-1.0.0.tgz oci://registry.example.com/charts

# Pull chart from OCI
helm pull oci://registry.example.com/charts/my-chart --version 1.0.0

# Install from OCI
helm install my-release oci://registry.example.com/charts/my-chart --version 1.0.0

# Inspect without installing
helm show values oci://registry.example.com/charts/my-chart --version 1.0.0

# Install a pinned digest (Helm 4): fails if the content doesn't match
helm install my-release oci://registry.example.com/charts/my-chart@sha256:<digest>

# Log out
helm registry logout registry.example.com
RegistryPush URL
GitHub Container Registryoci://ghcr.io/<org>/charts
Amazon ECRoci://<account>.dkr.ecr.<region>.amazonaws.com (login: aws ecr get-login-password | helm registry login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com)
Google Artifact Registryoci://<region>-docker.pkg.dev/<project>/<repo>
Azure Container Registryoci://<name>.azurecr.io/helm
Docker Huboci://registry-1.docker.io/<user>
  • The chart name and version come from the .tgz; the oci:// URL you push to is only the namespace. The pushed ref is <url>/<chart-name>:<version>.
  • helm push only takes packaged .tgz files: helm package first.
  • --version is required to pin; without it Helm picks the latest SemVer tag.
  • helm repo add, helm search repo and helm repo update do not work with OCI registries.

Test Yourself
  1. What command installs a chart with a dry run to preview rendered templates? helm install my-release bitnami/nginx --dry-run --debug

  2. How do you upgrade a release and automatically rollback if it fails? helm upgrade my-release bitnami/nginx --atomic

  3. What command shows the user-supplied values of an installed release? helm get values my-release

  4. How do you render templates locally without installing? helm template my-release ./my-chart -f values.yaml

  5. What hook annotation runs a Job before resources are upgraded? "helm.sh/hook": pre-upgrade

  6. How do you force a value to be treated as a string in --set? --set-string image.tag="1.25"

  7. What does --reuse-values do during an upgrade? It merges new overrides with existing values. Without it, all values reset to chart defaults plus your overrides.

  8. What command checks a chart for errors before deploying? helm lint ./my-chart

  9. How do you keep release history after uninstalling? helm uninstall my-release --keep-history

  10. What built-in object gives you the current release name in a template? .Release.Name

Common Gotchas

  • --reuse-values silently keeps old values. If a chart adds new required values in an upgrade, --reuse-values will not include them. Review chart changelogs before upgrading.
  • Forgetting helm lint before pushing. A YAML indentation error in templates will not show up until install time. Always lint and template-render locally first.
  • Hook resources are not managed by the release. Hooks are created and deleted based on their delete policy. If a hook Job fails, it may linger and block future upgrades.
  • helm upgrade without --install fails if the release does not exist. Use helm upgrade --install for idempotent CI/CD pipelines.
  • CRDs in crds/ are installed once and never upgraded or deleted by Helm. Upgrade CRDs yourself (kubectl apply --server-side -f crds/) or ship them as templates in a separate chart.
  • --set image.tag=1.10 becomes the number 1.1. Use --set-string (or quote in a values file) for versions, booleans-as-strings and long numeric IDs.
  • default swallows false. .Values.enabled | default true is always true. Use hasKey or ternary.
  • lookup returns empty during helm template and --dry-run (unless --dry-run=server), so templates must handle the empty case.
  • Release names are namespace-scoped; Helm commands default to the kubeconfig namespace. Forgetting -n makes helm list look empty and helm upgrade --install create a second release.
  • --atomic/--force are deprecated in Helm 4. Switch scripts to --rollback-on-failure/--force-replace once all your runners are on Helm 4.

One-Liner Summary

Helm is the package manager for Kubernetes -- master install, upgrade --atomic, template, hooks, and values.yaml overrides to deploy and manage complex applications repeatably.

Last updated: 2026-11-09