Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 38 ยท Dependencies and Hooks

Chart Dependencies and Subcharts

Declare dependencies in Chart.yaml, run helm dependency update, understand Chart.lock, version ranges, aliases and file:// subcharts, with a runnable resolver stand-in.

Real applications rarely stand alone. A web service needs a database, a cache, perhaps a message broker. Instead of copying someone else's manifests into your chart, Helm lets you depend on other charts. A chart that another chart depends on is called a subchart, and the chart that declares the dependency is the parent. When you install the parent, Helm renders the subcharts too and installs everything as one release.

This lesson shows how dependencies are declared, how versions are resolved, what Chart.lock is for, and how to keep several copies of the same subchart apart.

Declaring dependencies

Dependencies live in Chart.yaml (for charts with apiVersion: v2, which is every modern chart):

YAML
apiVersion: v2
name: shop
version: 0.3.0
appVersion: "1.8.2"
dependencies:
  - name: postgresql
    version: "^16.0.0"
    repository: "oci://registry-1.docker.io/bitnamicharts"
  - name: redis
    version: "~20.1.0"
    repository: "https://charts.example.com/stable"
    condition: redis.enabled
  - name: common-labels
    version: "0.2.0"
    repository: "file://../common-labels"

Each entry has a name (the subchart's own chart name), a version (an exact version or a range), and a repository that tells Helm where to download it. Three kinds of repository are common:

Repository value Meaning
https://... A classic HTTP chart repository with an index.yaml
oci://... An OCI registry (covered in OCI registries)
file://../path A chart in a local folder, handy in monorepos

Downloading with helm dependency update

Declaring is not downloading. Run this in the chart directory:

Terminal
helm dependency update ./shop

Helm reads the dependencies list, resolves each version range to the newest matching release, downloads the packaged .tgz files into charts/, and writes a Chart.lock file. After that, charts/ looks like this:

TEXT
shop/
  Chart.yaml
  Chart.lock
  values.yaml
  templates/
  charts/
    postgresql-16.4.2.tgz
    redis-20.1.7.tgz
    common-labels-0.2.0.tgz

You can also unpack a subchart into charts/postgresql/ if you want to patch it, but a packed .tgz is the normal state. The shortcut helm dependency list ./shop shows each dependency and whether it is ok, missing or unpacked.

Version ranges

Helm uses semantic versioning constraints. The most useful forms:

Constraint Allowed versions
1.2.3 exactly 1.2.3
^1.2.3 1.2.3 up to, not including, 2.0.0
~1.2.3 1.2.3 up to, not including, 1.3.0
>=1.2.0 <1.5.0 an explicit range
1.x any 1.y.z

For ^, a 0.x version is stricter: ^0.2.3 stops before 0.3.0, because pre-1.0 releases may change anything. Ranges are convenient, but they make builds depend on when you ran the command. That is exactly the problem Chart.lock solves.

The stand-in below mimics the resolver. It is not Helm's code (Helm uses a Go semver library), but it follows the same rules for these constraints.

Python Stand-in: resolve version ranges

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Chart.lock and helm dependency build

After dependency update, Helm writes Chart.lock with the exact versions it picked and a digest of the dependency list:

YAML
dependencies:
- name: postgresql
  repository: oci://registry-1.docker.io/bitnamicharts
  version: 16.4.2
- name: redis
  repository: https://charts.example.com/stable
  version: 20.1.7
digest: sha256:9f6c...
generated: "2026-03-02T10:15:00Z"

Commit this file. Then a teammate or a CI job runs:

Terminal
helm dependency build ./shop

build ignores the ranges and downloads exactly the locked versions, so everyone gets the same bits. If you edit Chart.yaml so the dependency list no longer matches the digest, build complains and asks you to run update again. Think of update as "choose" and build as "reproduce", the same relationship as composer update and composer install.

Python Stand-in: update chooses, build reproduces

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Aliases: two copies of one subchart

Sometimes you need the same chart twice, for example two Redis instances, one for sessions and one for a job queue. Give each entry an alias:

YAML
dependencies:
  - name: redis
    version: "~20.1.0"
    repository: "https://charts.example.com/stable"
    alias: sessions
  - name: redis
    version: "~20.1.0"
    repository: "https://charts.example.com/stable"
    alias: queue

Values for each copy sit under the alias name (sessions: and queue: in values.yaml), and the release gets two separate sets of objects. The next lesson explains how parent values reach subcharts.

Things that go wrong

  • Forgetting dependency update. helm install fails with "found in Chart.yaml, but missing in charts/ directory".
  • Committing charts/*.tgz. Many teams add charts/*.tgz to .gitignore and run build in CI; others commit them for offline installs. Pick one policy and state it in the README.
  • Wide ranges in production charts. >=1.0.0 pulls breaking changes on the next update. Prefer ~ or ^.
  • Wrong name. It must match the subchart's Chart.yaml name, not the folder or alias.

If a subchart does not need to be installed in every environment, add a condition or tags field. The next lesson covers both.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command downloads the exact versions recorded in Chart.lock?

    build reproduces the locked versions; update re-resolves ranges and rewrites the lock file.
  2. 2. What does the constraint ~1.4.2 allow?

    The tilde allows patch-level updates only.
  3. 3. How do you run two copies of the same subchart in one release?

    alias gives each copy its own name and its own values section.
  4. 4. Where does Helm place downloaded subcharts?

    Subcharts live in the parent chart's charts/ directory, usually as .tgz archives.

Summary

  • Dependencies are declared in Chart.yaml with name, version, repository.
  • helm dependency update resolves ranges, fills charts/ and writes Chart.lock; helm dependency build reproduces the lock.
  • Use ^ or ~ ranges, and commit Chart.lock.
  • alias lets one chart appear several times with separate values.

Next: Subchart Values and Global Values