Introduction

Including one Helm template inside another is supported, but it only works cleanly when you understand template names, scope, and indentation. Most "template inside template" problems in Helm 3 come from passing the wrong context, trying to include a file path instead of a named template, or forgetting to indent the rendered YAML correctly.

Use Named Templates, Not File Names

Helm does not include templates by file path. You define a named template, usually in _helpers.tpl, and then include it by name.

A basic helper might look like this:

1{{- define "mychart.labels" -}}
2app.kubernetes.io/name: {{ .Chart.Name }}
3app.kubernetes.io/instance: {{ .Release.Name }}
4{{- end -}}

Then include it in another template:

1apiVersion: v1
2kind: Service
3metadata:
4  name: {{ .Release.Name }}-svc
5  labels:
6{{ include "mychart.labels" . | nindent 4 }}
7spec:
8  selector:
9{{ include "mychart.labels" . | nindent 4 }}

The key details are the named template and the use of nindent so the included YAML lines up with the surrounding document.

Including A Template From Another Template

You can absolutely include helper A inside helper B:

1{{- define "mychart.selectorLabels" -}}
2app: {{ .Chart.Name }}
3release: {{ .Release.Name }}
4{{- end -}}
5
6{{- define "mychart.commonLabels" -}}
7{{ include "mychart.selectorLabels" . }}
8managed-by: Helm
9{{- end -}}

And then render mychart.commonLabels elsewhere:

metadata:
  labels:
{{ include "mychart.commonLabels" . | nindent 4 }}

This works because both helpers are defined by name and both receive the current chart context through ..

Pass The Right Scope

Scope is the most common source of bugs. Inside range, with, or nested helpers, . can change. If the included template expects the root chart context, pass $ instead:

1{{- range .Values.deployments }}
2apiVersion: apps/v1
3kind: Deployment
4metadata:
5  name: {{ .name }}
6  labels:
7{{ include "mychart.commonLabels" $ | nindent 4 }}
8spec:
9  replicas: {{ .replicas }}
10{{- end }}

In that example, . inside the loop is one deployment item, not the whole chart object. Passing $ preserves access to .Chart, .Release, and global values inside the helper.

If you need both the root context and item-specific values, pass a dictionary:

1{{- define "mychart.image" -}}
2image: {{ .root.Values.image.repository }}:{{ .item.tag }}
3{{- end -}}
4
5{{- range .Values.deployments }}
6{{ include "mychart.image" (dict "root" $ "item" .) }}
7{{- end }}

That pattern keeps helper interfaces explicit.

include Versus template

Helm provides both include and template. The practical difference is that include returns a string, so you can pipe it through indent, nindent, trim, or quote. For YAML composition, include is usually the better tool.

For example:

annotations:
{{ include "mychart.annotations" . | nindent 2 }}

If you use template instead, you lose some control over formatting because it writes directly to the output stream.

Common Pitfalls

The biggest mistake is writing something like include "templates/common.yaml" .. Helm wants a template name from define, not a file path.

Another common bug is lost scope inside a range or with. If a helper suddenly cannot see .Chart.Name or .Values, check whether you passed . when you should have passed $.

Indentation errors are also common. The included text may be correct by itself but invalid once inserted into a YAML document. Pipe included content through nindent at the point where it is rendered.

Finally, avoid returning partial YAML fragments whose shape is unclear. Helpers are easier to debug when they return a predictable block such as labels, annotations, or image settings.

Summary

• In Helm 3, templates can include other templates as long as they are defined by name.
• Use include, not file paths, to render a named helper template.
• Pass the correct scope, and use $ when the helper needs the root chart context.
• Use dict when a helper needs both global and item-specific data.
• Pipe included output through nindent so the final YAML stays valid.