# ytt: templating that parses YAML instead of rewriting it as text

> A Carvel tool that templates YAML documents through their structure rather than through text substitution, with Starlark as the expression language and overlays for environment specific customisation. Suited to teams already generating Kubernetes manifests, and a poor fit if your inputs are mostly non YAML files.

**carvel-dev/ytt** — YAML templating tool that works on YAML structure instead of text

- Repository: https://github.com/carvel-dev/ytt
- Website: https://carvel.dev/ytt
- Stars: 1,885 · Forks: 169
- Language: Go
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/carvel-dev-ytt

## Structure awareness is the whole argument against text templating

ytt is described as a templating tool that understands YAML structure, and the README makes the case for that in terms of what text templating forces on you: YAML value quoting and manual template indentation. Those are not cosmetic problems. In a text based template, whether a substituted value needs quotes depends on what is being substituted, so the template author has to reason about the YAML grammar rather than about the configuration.

A structure aware tool parses the document first and substitutes into the parsed form. The output is assembled as YAML, so indentation and quoting follow from the data rather than from the template author's care.

The project is part of Carvel, has a homepage at carvel.dev/ytt, and is licensed under Apache 2.0. Releases are published as tags, with v0.55.3 on 2026-09-23, v0.55.2 on 2026-08-14 and v0.55.1 on 2026-06-01.

## Starlark is the expression language, not Go templates

Templates in ytt are evaluated in Starlark, which the README calls a Python-like programming language included in the project. The dependency list confirms it is not built in from the standard library but vendored at a pinned revision:

```text
module carvel.dev/ytt

go 1.26.4

require (
  github.com/BurntSushi/toml v1.5.0
  github.com/k14s/starlark-go v0.0.0-20200720175618-3a5c849cc368
  github.com/spf13/cobra v1.10.2
  github.com/stretchr/testify v1.8.4
)
```

Two things follow from that choice. Template authors get a language with real control flow rather than the pipe-and-argument shape of Go templates, and the execution happens in a sandbox, which the README lists as a feature providing a secure and deterministic environment for template execution.

The deterministic part is the other half of the pitch. The README pairs custom validations with fast and deterministic execution, and argues that combination gives faster feedback loops when creating and testing templates.

## Trying it means the playground, not a local build

There is no install command in the README and none in the repository files, so the documented paths are the release artefacts and the playground. Binaries come from the releases page on GitHub or from the Homebrew Carvel tap.

For evaluation, the README points at an online playground, and there is a way to run that playground locally once you have a binary:

```bash
ytt website
```

That single command is the whole first-run experience. The examples used by the playground are kept in the repository under examples/playground, which is also the place to read working input when you want something more than a one screen demonstration.

For editor support, the README links a VS Code extension providing syntax highlighting for ytt files. That is a small thing, but with a templating language in the middle of your configuration it is the difference between understanding a file and guessing at it.

## Data values separate template from environment

The reusability story rests on data values, the mechanism through which a caller supplies configuration to a template. The example directory shows the shapes people actually need: examples/data-values/ for the basic case, examples/data-values-multiple-envs/ for the same template driven by several environments, examples/data-values-required/ for values the template refuses to run without, examples/data-values-directory/ for supplying a directory of values, and examples/data-values-wrap-library/ for packaging a values set as a reusable library.

The README summarises this as reusing the same configuration in different environments by applying environment specific values. The examples-required directory is the interesting one for adoption decisions, because it represents the case where a missing value is an error rather than a default, and that is the behaviour that keeps a template from silently producing a wrong manifest.

None of these are documented as CLI flags in the README, so the concrete invocation syntax for pointing ytt at a values file is something you take from the examples rather than from the project overview.

## Overlays are the second idea, and they are separate from data values

Overlays are described in the README as the advanced configuration feature that helps users manage the customization required for complex software, with an example linked in the playground. Conceptually they are different from data values: data values feed parameters into a template, whereas overlays modify the output that a template already produced.

The example tree shows how wide that surface is. There is a plain examples/overlay/, then overlay-remove-resources/, overlay-not-matcher/ for matchers that deliberately do not match, overlay-regular-files/ for patching files other than YAML documents, and overlay-in-config-map/ and overlay-all-containers/ for reaching inside generated structures. There is also k8s-add-global-label/, k8s-adjust-rbac-version/, k8s-update-env-var/ and k8s-relative-rolling-update/, which are concrete Kubernetes customisations.

overlay-remove-resources/ is worth reading first for anyone evaluating the tool. It documents the case where the right answer is subtraction, and a templating tool that can only generate is not much use for evolving a base manifest.

## The examples directory is the real documentation for practice

The example count is itself a signal about the state of the project. Beyond templating basics there are examples/concourse-overlay/ for a CI system, examples/helm-ytt-post-renderer/ for ytt acting after Helm renders a chart, and an examples/eirini/ directory.

The Helm post-renderer example is the one that answers the most common adoption question. The repository names the integration example helm-ytt-post-renderer, indicating that the two tools can be used together. For teams with an established chart workflow, that is a much cheaper entry than replacing templating entirely.

examples/integrating-with-ytt/ exists for embedding the tool, and the README points to its apis.md for teams building ytt into their own tooling. examples/load-paths/ covers how ytt resolves which files it reads, which is the first thing that surprises people when a template output differs between machines.

## Maintenance, packaging and project governance

The last push was on 2026-10-15, and the default branch is develop rather than main. 

Distribution is by goreleaser:.goreleaser.yml at the root produces the binaries on the releases page. The Go module requires go 1.26.4 and vendors its dependencies into a vendor/ directory, allowing builds without fetching modules from a proxy.

Governance files are present in the usual Carvel arrangement: GOVERNANCE.md, MAINTAINERS.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md and NOTICE, plus a ROADMAP.md. The README also links an OpenSSF Best Practices badge and points to the Carvel community meetings and the #carvel channel on Kubernetes Slack.

Licensing is Apache 2.0 with a NOTICE file at the root, which is the standard obligation set for redistributing a binary built from this source.

## Where ytt is the wrong tool

The boundary follows from the premise. ytt is a YAML structure templating tool, so a pipeline whose real work is rendering text files, scripts or arbitrary configuration formats has nothing to gain from it and pays the Starlark learning cost for nothing.

The second boundary is organisational. Overlays and data values are two overlapping customisation systems, and the example directory shows that choosing between them per change is a decision someone has to make consistently or the output becomes hard to reason about. A team without a convention for which one to reach for will accumulate overlay patches that quietly override values set elsewhere.

The third is the Starlark sandbox. It is a deliberate security boundary, which is the right call for a tool that renders configuration in CI, but it also means template authors cannot reach for arbitrary host capabilities, so a template that needs an external lookup has to receive that value from the caller instead.

## Conclusion

Adopt ytt if your configuration pipeline renders YAML for Kubernetes and you want template authors to stop fighting indentation and quoting, and if you are willing to write Starlark rather than Go templates. Do not adopt it for templating arbitrary text files, because the README frames the project as a tool that understands YAML structure, and non YAML inputs fall outside that model. Verify first that you can live with the Starlark sandbox, since the README lists sandboxing as a deliberate feature providing a secure and deterministic execution environment, and check the example directories for data values and overlay files before designing your own conventions.

## FAQ

### How do I install ytt?

The README does not give an install command. It points to prebuilt binaries on the GitHub releases page and to the Homebrew Carvel tap.

### Which language does ytt use for templates?

ytt uses Starlark, a Python-like language that the README describes as fully featured and included in the project. The Go module pins github.com/k14s/starlark-go rather than using an in tree interpreter.

### What is the difference between data values and overlays in ytt?

Data values supply parameters into a template so the same configuration can be reused across environments. Overlays modify the output a template has already produced, and the examples directory includes cases for removing resources, patching regular files and editing structures inside a ConfigMap.

### Can ytt be used together with Helm?

The repository contains an example named helm-ytt-post-renderer.

### Is ytt sandboxed when it executes templates?

Yes. The README lists sandboxing among the features and describes it as providing a secure and deterministic environment for template execution.

## Sources

- [carvel-dev/ytt on GitHub](https://github.com/carvel-dev/ytt)
- [License: Apache-2.0](https://github.com/carvel-dev/ytt/blob/develop/LICENSE)
- [Project website](https://carvel.dev/ytt)
- [README](https://github.com/carvel-dev/ytt/blob/develop/README.md)
- [Releases](https://github.com/carvel-dev/ytt/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/carvel-dev-ytt