v1.2.22026-11-11
🏎️ Performance Improvements
Faster dependency discovery in large repositories
run --all, and find or list with --dependencies, are faster in large repositories, including ones with no dependency blocks. The time spent linking units to their dependencies now grows linearly with the number of units instead of quadratically.
In benchmarks on an AMD Ryzen AI Max+ 395, discovering units and their dependencies in a generated repository of 10-unit dependency chains:
| units | before | after |
| --- | --- | --- |
| 10 | 0.63ms | 0.63ms |
| 100 | 5.2ms | 5.0ms |
| 1,000 | 56ms | 47ms |
| 10,000 | 1.32s | 443ms |
At 10,000 units, memory allocated during discovery dropped from 8.6 GB to 1.9 GB.
Faster discovery with dependent filters
Terragrunt wastes less time resolving symlinks in discovery. Dependent filters, such as --filter '...vpc' were able to reduce the number of wasted syscalls to resolve symlinks, improving dependent discovery.
On a repository of 1,024 units, discovery with a dependent filter took 30% less time from the repository root and 47% less time from the target unit's directory on an M3 Max. It also allocated 12-16% less memory.
Faster discovery of dependencies
Discovery prepared to read a terragrunt.stack.hcl in every directory named by a dependency or dependencies block, even when the directory was a unit. It now does that work only when the stack file exists.
In benchmarks on an AMD Ryzen AI Max+ 395, selecting the dependents of a unit that every other unit depends on, run from that unit's directory:
| units | before | after |
| --- | --- | --- |
| 10 | 2.9ms | 2.3ms |
| 100 | 118ms | 86ms |
| 1,000 | 11.1s | 8.0s |
At 1,000 units, memory allocated during discovery dropped from 26.7 GiB to 10.3 GiB.
💡 Tips Added
inputs-read-not-tracked — Points at files read in inputs that reading filters miss
Terragrunt does not track a file read in inputs. A unit with this configuration is not selected by --filter 'reading=config.yml' or by a Git filter when config.yml changes:
``hcl
terragrunt.hcl
inputs = {
message = yamldecode(file("config.yml")).message
}
`
The same applies to inputs in an autoinclude block of a stack file.
Commands that track reads, such as run --all with a reading or Git filter and find --reading, now print the inputs-read-not-tracked tip pointing at each such read:
`text
TIP (inputs-read-not-tracked): Terragrunt does not track files read in inputs, so reading and Git filters miss the units and stacks that read them.
Untracked file read in inputs
--> app/terragrunt.hcl:4:24
|
4 | message = yamldecode(file("config.yml")).message
| ^^^^^^^^^^^^^^^^^^ Read the file in locals and reference the local here.
Untracked file read in an autoinclude block's inputs
--> live/terragrunt.stack.hcl:16:29
|
16 | policy = templatefile("policy.json.tftpl", { rolearn = dependency.iam.outputs.rolearn })
| ^^^^^^^^^^^^^^^^^^^
|
= Mark the template as read with markasread in the stack's locals, then pass the local as the path here.
See https://docs.terragrunt.com/features/filter/attributes#reading-based-expressions
`
See Reading-Based Expressions. Suppress the tip with --no-tip inputs-read-not-tracked or --no-tips.
🔒 Strict Controls Added
cas-source-inside-stack strict control
A unit or stack block with updatesourcewith_cas could set a source inside the directory of its own stack file, e.g. a catalog with its stack at the root and its units under units/:
`hcl
catalog/terragrunt.stack.hcl
unit "foo" {
source = "./units/foo"
updatesourcewith_cas = true
path = "foo"
}
`
Stack generation copies the stack directory whole. For a stack "bar" block with source = "../catalog", the generated stack contained the unit twice, and run --all ran both, the copy without the values its stack gives the generated unit:
`text
.terragrunt-stack/bar/.terragrunt-stack/foo
.terragrunt-stack/bar/units/foo
`
Existing support will be retained for v1.x for backwards compatibility, to obey the Terragrunt 1.0 guarantees.
Terragrunt now warns about each such block:
`
WARN Setting the source of a unit or stack block with updatesourcewith_cas to a directory inside the stack directory is deprecated and will be removed in a future version of Terragrunt. Stack generation copies the stack directory whole, so run --all also runs the copy. Move the source out of the stack directory, and select the stack with a // subdirectory in its source.
WARN stack bar: unit "foo" in terragrunt.stack.hcl sets updatesourcewith_cas on source "./units/foo" inside the stack directory, so the generated stack also contains a copy of it; move the source out of the stack directory and select the stack with a // subdirectory in its source
`
With the new cas-source-inside-stack strict control enabled, each of those blocks is an error instead:
`bash
terragrunt stack generate --strict-control cas-source-inside-stack
`
Move the stack into a subdirectory of the catalog, e.g. stacks/bar, keep its sources outside that subdirectory, and select it with source = "../catalog//stacks/bar". The cas-source-inside-stack control is also part of the deprecated-configs group.
🧪 Experiments Added
no-dot-terragrunt-cache experiment adds a terraform.nodotterragrunt_cache attribute
Enable the no-dot-terragrunt-cache experiment and set nodotterragrunt_cache = true in the terraform block of a unit without a source. Terragrunt then runs OpenTofu/Terraform in the unit directory instead of a copy in .terragrunt-cache, so local module paths resolve as written. The attribute is merged through include.
`hcl
terraform {
nodotterragrunt_cache = true
}
`
`bash
terragrunt run --experiment no-dot-terragrunt-cache -- plan
`
Setting it to true together with a source, or without the experiment enabled, returns an error.
variables-block experiment adds a variables block
Enable the variables-block experiment to set OpenTofu/Terraform variables with a variables block. Its kind attribute chooses how Terragrunt passes the inputs: TFVAR environment variables (env, the default), a terragrunt.auto.tfvars file (tfvar), or a terragrunt.auto.tfvars.json file (json). Writing inputs to a file avoids the operating system's limit on the size of a process environment, which a unit with many or large inputs can exceed.
`hcl
variables {
kind = "tfvar"
validate = true
inputs = {
vpcid = dependency.vpc.outputs.vpcid
}
}
`
`bash
terragrunt run --experiment variables-block -- plan
`
With the experiment enabled, terragrunt.auto.tfvars and terragrunt.auto.tfvars.json are reserved names in .terragrunt-cache. Terragrunt removes a file with either name from the cache when the unit has no inputs of that kind, so rename any such file in a unit, module, or generate block.
🧪 Experiments Updated
mcp-command — terragrunt mcp` ser
v1.2.12026-10-23
⚙️ Process Updates
Go bumped to v1.27.3 for a security fix
The version of Golang used to compile the Terragrunt binary has been updated from v1.27.2 to v1.27.3.
Go v1.27.3 is a security release. It fixes CVE-2026-111943 in crypto/x509: certificate verification now rejects chains that contain a small set of untrusted intermediate certificates. Terragrunt uses this verification for every HTTPS connection it makes, including source downloads, provider registry lookups, and remote state backends. We recommend upgrading.
Terragrunt runs git, hg, and smbclient source downloads itself
Terragrunt downloaded git::, hg::, and smb:// sources through the getters built into the go-getter library, which started git, hg, and smbclient on their own. Terragrunt now implements these getters itself and starts those programs the same way it runs every other command.
Downloads should behave as they did before. If you find any functional difference, open an issue.
Because the downloads now go through Terragrunt's own command handling, Terragrunt's tests can cover them without a real git, hg, or smbclient install or a remote server, which makes regressions in source downloads easier to catch.
🏎️ Performance Improvements
Faster parsing of shared configuration
Repositories where every unit includes a root.hcl that loads shared files with readterragruntconfig now parse much faster.
- Each unit used to parse those shared files itself, so a common.hcl that runs yamldecode(file(...)) on a large YAML file decoded it once per unit. Terragrunt now parses each file once and gives every unit the same result, and parses it again only when the file, or a file it reads, changes during the command. run --all parses it a second time when the run starts, after discovering units. A file whose result can differ between units, like one that calls getoriginalterragrunt_dir() or has dependency blocks, is still parsed per unit.
- Since v1.1.2, discovery parsed every included configuration twice, once for its feature flag defaults and once to merge it. It parses each include once again, and skips includes with mergestrategy = "nomerge" that it would only have thrown away.
- Locals and inputs went through a JSON encoding round trip on their way into Terragrunt. Terragrunt now converts them directly.
In benchmarks on an Apple M3 Max, discovering units and their dependencies in a generated repository whose units read a 48 KB YAML file through readterragruntconfig:
| units | before | after |
| --- | --- | --- |
| 100 | 819ms | 59ms |
| 500 | 3.60s | 201ms |
| 1,000 | 7.01s | 379ms |
| 5,000 | 34.2s | 1.88s |
Memory allocated during discovery dropped by about 95%.
Faster discovery with path filters
Terragrunt now analyzes --filter expressions before discovery starts and uses them to narrow the filesystem walk it does during discovery. Filters that name specific paths let Terragrunt skip most of the walk, or walk only the directories those paths can match.
On a repository of 10,000 units, discovery with a filter like --filter './doublestar/glob/**', matching 1,250 of those units, took 27 ms instead of 224 ms. A filter like --filter './path/to/specific/unit', which names a single unit, took under 1 ms instead of 215 ms. Discovery selects the same units as before. It still walks the whole working directory when there is no filter, when every filter is negated, or when any filter can select a unit anywhere, such as name=vpc or ...vpc.
Units that share a run_cmd result run the command once
Units share a runcmd result when the call uses --terragrunt-global-cache, or when it is in a file they read with readterragrunt_config. Discovery parses units concurrently, so several of them could start the command before any had cached its result, and run --all could run a shared command once per unit.
Units now wait for the first run and reuse its result. If that run fails, the next unit runs the command itself.
📖 Documentation Updates
Azure and GCP examples across the docs
The Overview now has Azure and GCP examples for every step. The Azure examples create a resource group and a virtual network in eastus and westus2, with state in an azurerm backend. The GCP examples create a VPC network and a Cloud Router in us-central1 and us-east1, with state in a gcs backend.
The code for each step is in test/fixtures/docs/02-overview-azure and test/fixtures/docs/02-overview-gcp. Integration tests apply and destroy each step in both directories.
These pages also have Azure and GCP examples now:
- Units shows an env.hcl that generates the provider for every unit in an environment.
- Includes shows a root.hcl that configures the backend and generates the provider.
- Importing shows how to import resources by resource ID.
- backend bootstrap, backend migrate, and backend delete show what each command creates, moves, or deletes for an azurerm or gcs backend.
- In Patterns, the "Keep your backend configuration DRY" pattern sets an azurerm or gcs backend once in root.hcl.
Authentication now has a page for each cloud provider. The Azure page covers signing in with the Azure CLI, a service principal, OIDC, or a managed identity. The GCP page covers gcloud, a service account key, Workload Identity Federation, and an attached service account. Each lists the roles its state backend needs. The AWS content moved to the AWS page, and links to its old headings redirect there.
State Backend also has a page for each backend now: S3, GCS, and Azure Storage. Links to the old backend headings redirect to the new pages. The GCS page now covers what the Azure section already did: the order Terragrunt resolves credentials in, the settings Terragrunt reads without passing them to OpenTofu/Terraform, and the backend's known limitations.
Pick a cloud provider in any example tab, and every tab on the page switches with it. Other pages open on the same provider when they have a tab for it, and show AWS when they don't.
🐛 Bug Fixes
Reading a unit's outputs no longer collides with that unit's own run
In run --all, a unit could run at the same time as another unit reading its outputs, e.g. with --queue-ignore-dag-order, or when a Git filter plans the destroy of a re
v1.2.02026-10-21
Terragrunt v1.2.0 是一次分量十足的 minor 版本:11 项实验功能集体转正——block-iteration、oci、bounded-discovery、catalog-format、mutable-generate、optional-dependency-outputs、optional-hooks、azure-backend、version-attribute、profiling、dependency-fetch-output-from-state 今后可直接使用,不必再开实验开关。
破坏性变更有两处。base64gzip() 改用 Go 1.27 的 gzip 编码器,输出与旧版不同;依赖该值做比较的资源(例如设置 userdatabase64 且 userdatareplaceonchange 为 true 的 awsinstance)升级后首次 plan 可能触发替换。需要编码长期保持稳定,可改用实验性的 base64gzipcompat(),它永久返回 v1.1.3 的输出:
``bash
terragrunt run --all --experiment base64gzip-compat -- plan
`
`hcl
inputs = {
userdatabase64 = base64gzipcompat(file("${getterragrunt_dir()}/user-data.sh"))
}
``
另一处,S3 状态桶引导不再附加 RootAccess 策略语句。该语句把 s3:* 授予整个 AWS 账户而非仅根用户,状态文件常含密钥,权限面过宽;桶本就归账户所有,移除并不影响使用。
v1.2.0-rc3预发布2026-10-15
v1.2.0 的第三个也是最后一个候选版发布:沿用上一版的十一项实验,另修了九个问题。若无人报阻断性缺陷,正式版即以此内容发布。
两处变更需要留意。一是 base64gzip() 改用 Go 1.27 的 gzip 编码器,编码值随之改变;凡拿该值做比较的资源(如 userdatabase64 配合 userdatareplaceonchange = true),升级后首次 plan 可能触发替换。要求结果稳定的,改用实验函数 base64gzipcompat(),它永久返回旧输出,需开启 base64gzip-compat 实验。二是初始化 S3 状态桶时不再附加 RootAccess 桶策略——该语句把 s3: 授予整个账户,而状态文件常含密钥;skipbucketrootaccess 随之废弃,改用 enablebucketrootaccess 按需开启。已有桶保留原语句,可依文档自行移除。
v1.2.0-rc2预发布2026-10-07
Terragrunt v1.2.0 第二个候选版发布:沿用 rc1 的十一项实验,并修复了 CAS、catalog、Provider Cache Server 与 exclude 块中的多处缺陷。后续 RC 会继续跟进实验相关修复、紧急问题与文档完善,建议先在低环境试用并到 GitHub discussion 反馈。
有两处破坏性变更值得留意。其一,base64gzip() 改用 Go 1.27 编码器的输出,升级后首次运行可能触发资源替换;若编码结果必须保持稳定,可开启 base64gzip-compat 实验改用 base64gzipcompat()。其二,S3 状态桶不再自动附加 RootAccess 桶策略语句,skipbucketrootaccess 随之废弃,需要账户 root 访问时改用 enablebucketroot_access,已有该语句的桶不受影响。
v1.2.0-rc1预发布2026-09-24
Terragrunt v1.2.0 首个 RC 发布,一次性收尾了 block-iteration、oci、bounded-discovery、catalog-format、mutable-generate、azure-backend、profiling 等 11 项实验;后续 RC 主要补充这些实验的缺陷修复与文档改进。
有两处破坏性变更需要留意。其一,base64gzip() 改用 Go 1.27 编码器,压缩结果与旧版不同——像 awsinstance 这类用它填充 userdatabase64 且开启 userdatareplaceonchange 的资源,升级后首次执行可能触发重建;必须保持编码值稳定的话,启用 base64gzip-compat 实验改用 base64gzipcompat(),其输出与 v1.1.3 恒定一致。其二,S3 状态桶不再附加 RootAccess 桶策略语句,skipbucketrootaccess 随之废弃(仍可用但会告警),需要时改设 enablebucketrootaccess 为 true。已存在的桶不受影响。
v1.1.62026-09-21
修复了 Windows 下 Git 过滤器失效的问题。此前用 find、list、browse 配合 --filter '[main...HEAD]' 这类 Git 过滤时,如果本次改动只涉及嵌套目录里的 unit 配置(如 nested\path\terragrunt.hcl),命令会直接返回空结果。根源在 v1.1.5 引入的 worktree 优化:它只检出有改动的单元目录,而 Windows 上这些目录用反斜杠拼接,与 Git 文件清单中的正斜杠路径对不上,结果一份都没匹配、什么也没检出。现在各平台统一按 / 分隔符查找,嵌套目录的过滤恢复正常。
v1.1.52026-09-14
✨ New Features
duplicate-dependency-labels also catches a shared config_path
Two dependency blocks with different labels can point at the same configpath. Both parse, so the same unit is declared twice, and the two blocks drift apart as soon as one gains a mockoutputs or skip_outputs the other lacks:
``hcl
dependency "vpc" {
config_path = "../vpc"
}
dependency "network" {
config_path = "../vpc"
}
`
Terragrunt now warns when it finds this, alongside the existing warning for two blocks sharing a label. With the duplicate-dependency-labels strict control enabled, the warning becomes an error naming both addresses and the path they share:
`text
/path/to/terragrunt.hcl: dependencies vpc and network both point at ../vpc; declare that dependency once and reference it under one name
`
🏎️ Performance Improvements
Fewer remote probes for sources shared across units
run --all asked the remote what a source resolved to once per unit, so a hundred units sharing one module made a hundred requests. Each of them then read the same commit out of the store for itself.
Units that resolve the same source at the same time now share one probe, and units that need the same Git commit share the work of reading it into the CAS.
Measured over 100 units pointing at one Git module, counting the Git commands a run spawns:
| 100 units, one shared module | Before | After |
| --- | --- | --- |
| First run: git ls-remote | 100 | 1 |
| First run: reading the commit into the store | 202 | 4 |
| First run: Git commands in total | 304 | 7 |
| Later run, source on a branch | 100 | 1 |
| Later run, source on a version tag | 100 | 0 |
The last row needs the offline-cas experiment described below; the rest apply to every run. Against a local Git server the first run went from roughly 5 seconds to 0.3, and a later run from 1 second to 0.1. A real remote makes each avoided ls-remote worth more, since it costs a network round trip rather than a local process.
The new offline-cas experiment goes a step further and has the CAS record each probe answer in the store, so a later run can skip the request. How long it trusts an answer depends on the source:
- A source pinned to a specific revision keeps its answer for 24 hours: a semantic version tag, an S3 object version, an OCI manifest digest, an exact registry module version, or a full Mercurial changeset node.
- A source that can change upstream, such as a Git branch or an OCI tag, gets a fresh probe on every run, so a push or an upload shows up immediately.
The experiment also unlocks three flags that change how the recorded answers are used:
- --cas-offline never contacts a remote. Sources come from the local store and the recorded answers, and anything missing is an error rather than a fetch.
- --cas-refresh ignores the recorded answers for one run and asks every remote again.
- --cas-probe-ttl trusts a changeable source's answer for a duration you choose, such as 10m.
See Recorded probes and the offline-cas experiment.
Faster first-time source downloads
The first time Terragrunt stores a repository in the Content Addressable Store (CAS), it copies the content of every file out of the clone. It used to launch a separate git process for each one, and on repositories with many files those launches dominated the time.
Terragrunt now reads a repository's content through a single long-lived git process, and stores several files at a time.
In benchmarks on an Apple M3 Max:
| files | before | after | change |
| --- | --- | --- | --- |
| 200 | 2.16s | 0.38s | -83% |
| 1,000 | 10.41s | 0.74s | -93% |
| 3,000 | 34.25s | 1.69s | -95% |
The saving grows with the number of files.
This applies when the CAS does not already hold the content, such as the first use of a new module version or a run against an empty store. Downloads that the CAS can already serve skipped this work before and are unchanged.
CAS store improvements
The CAS no longer writes a lock file beside each object it stores. A store had one lock file for every file and every directory listing it cached, so ~/.cache/terragrunt/cas held roughly twice as many entries as the cached content needed. Lock files already written stay where they are; deleting the store while no Terragrunt process is running against it reclaims them, and the store rebuilds without them.
Terragrunt preserves a couple of files from a repository's .git directory when it materializes a Git source, and which files those are depends on the command. Those files used to be folded into the stored entry for the commit, so the first command to fetch a commit decided what every later command received from it: a commit first cached by stack generate, which asks for none of those files, left a later run against the same commit without them. Each file is now recorded against the commit on its own, and a command receives exactly the files it asked for whether the commit was already cached or not.
A source pinned to a full commit SHA now asks the remote for that commit alone, one commit deep, instead of fetching every branch and tag with full history. Remotes that will not serve a commit by name, such as an older or locked-down server, still get the full fetch, so pinning keeps working everywhere. Where the remote does serve it, the first fetch of a large repository transfers the pinned commit and nothing else.
The numbers below come from micro-benchmarks run against a git server on the same machine. The fixture is a 500-commit history whose pinned commit sits 100 commits behind the tip.
| Measurement | Before | After | Change |
| --- | --- | --- | --- |
| Git objects kept after fetching the pinned commit | 543 | 43 | 92% fewer |
| Time to fetch the pinned commit | 575ms | 482ms | 16% faster |
Against a real remote the pinned fetch saves more than the table shows, since the objects it no longer asks for would also have to cross the network.
Faster dependents filters
A filter with ... before its target, such as ...vpc`, finds dependents by walking the directory tree around the target and parsing each configuration it passes to see whether it depends on the target. That walk parsed every configuration from scratch, even one Terragrunt had earlier in the same command, and it runs again from each dependent it finds. On a large repository, one query could read and parse the same unrelated unit once per dependent it selected.
Terragrunt now reuses a configuration it has already parsed, so each unit is read from disk about once per query.
In benchmarks on an Apple M3 Max, querying the dependents of a unit from its own directory, where every other unit depends on it:
| units | before | after |
| --- | --- | --- |
| 10 | 15.3ms | 10.0ms |
| 50 | 235ms | 150ms |
| 200 | 3.19s | 2.09s |
From the repository root, where the walk only has to rule out the units that do not depend on the target, the same query over a 1,024-unit repository went from 250ms to 131ms.
Faster file work, especially on small CI runners
Terragrunt frequently does a lot of small file operations at once: copying a module into its working directory, storin
v1.1.42026-08-27
这版有三项改动。新增 duplicate-dependency-labels 严格控制:同一配置里写两个同名 dependency 块此前静默通过,引用一律取后者,先前的块被无声覆盖而不报错;现在会告警,启用该控制后升级为错误,并指明冲突的标签地址。terragrunt scaffold 改为弹出交互表单收集输入值,与 Catalog TUI 行为一致,按 esc 放弃即不写入;传 --not-interactive、stdin 非终端或源本身无输入时仍跳过表单,CI 中的脚手架不受影响。启动提速:未指定 --tf-path 时不再靠运行 tofu -version 探测二进制,省掉了每次命令开头的进程启动,--version 基准快约 1.7 倍;副作用是 tofu 在 PATH 上却无法运行时会直接选中并报错,不再静默回退到 terraform,可用 --tf-path 或 TGTFPATH 手动指定。另修复了自动包含覆盖依赖时仍先解析原 config_path、导致单元解析失败的问题。
v1.1.32026-08-13
本版集中修复六个问题。values. 输入由 autoinclude 补齐、而 values 文件未定义时,不再抛出 Unsupported attribute,注入值正常生效;generate 块的 overwriteterragrunt 与 removeterragrunt 现在能处理首行后没有换行的文件(含空文件);依赖输出直读远端 state 时,S3 桶尚未创建同样回退到 mockoutputs,plan、validate 可在后端初始化前解析出桩数据;开启 fast-copy 后,由 includeincopy 带上的隐藏目录保留源权限,与关闭该控制时的复制行为一致;--filter 以否定开头的查询,后续正向表达式恢复生效,'!name=foo | name=bar' 从返回三个组件收窄为只返回 bar;此外修复了 provider 缓存服务在缓存目录就绪前就响应请求的竞态,避免归档与 lock 文件残留工作目录。