Terragrunt v1.0.6 Release - Deep Merge and Performance

The Terragrunt project released version v1.0.6 on May 25, 2026, introducing a recursive directory safety check and a new experimental function for deep merging configurations. This update addresses several critical panics in the rendering pipeline and optimizes the discovery phase for large repositories by allowing operators to skip authentication commands when only parsing units.

The full release notes and downloads are on the GitHub release page.

A significant fix in this release addresses a hang that occurred when the download_dir attribute was set to a non hidden subdirectory of the working unit. Previously, if an operator configured the cache directory to a local path like cache instead of the default .terragrunt-cache, the tool would copy modules into that directory and then discover them as new units during the next scan. This created an infinite recursion that consumed system resources and prevented the execution of plan or apply operations.

The project now includes a check that identifies when the destination path for module downloads resides within the source tree. Instead of entering a loop, the tool now produces an immediate error that identifies both the source and destination paths. This change ensures that misconfigured local caches do not block CI pipelines or local development workflows. It is a breaking change for any existing configurations that relied on this behavior, though such configurations were likely already failing to complete.

This release introduces the deep-merge experiment, which adds a native deep_merge function to the HCL execution environment. This function is particularly useful for platform engineers who manage complex input hierarchies where standard map merges are insufficient. Unlike a shallow merge that simply replaces top level keys, deep_merge recursively combines nested maps and objects.

Operators can now compose inputs from multiple sources such as JSON files, YAML files, and other HCL maps with fine grained control. When keys overlap, values from later arguments override earlier ones, while nested structures are merged rather than replaced. Lists are appended together, and null values are ignored. To use this feature, the deep-merge experiment must be enabled via the TG_EXPERIMENT environment variable or the --experiment flag. This addition reduces the need for external pre processing scripts when assembling environment specific variables from shared data sets.

For users operating within large mono repositories, the discovery phase of a run-all command can be a major bottleneck. The new opt-out-auth experiment addresses this by introducing the --no-discovery-auth-provider-cmd flag. By default, Terragrunt runs the configured authentication provider command for every unit it discovers to ensure functions like get_aws_account_id can resolve correctly during parsing.

In large environments, running an external auth command hundreds of times during the initial scan adds significant wall clock time. With this flag enabled, the tool skips these calls during the discovery phase and only executes them when a unit is actually selected for execution. This optimization can drastically reduce the time spent in the initial queue building phase. Operators should use this when they are certain that their discovery logic does not strictly depend on credentials generated by the auth command.

Several bug fixes in this release improve the reliability of the rendering and stack management logic. A regression in how the tool cached binary versions has been resolved. Previously, if both tofu and terraform were present on the system path, the tool could incorrectly cache the version of the default binary even when a specific terraform_binary was configured. This led to incorrect compliance checks against version constraints. The cache is now properly scoped to the specific binary path being queried.

The terragrunt render command received fixes for crashes related to exclude and catalog blocks. Certain attributes like no_run or default_template caused panics during the rendering process because they were not correctly handled in the output pipeline. Additionally, the handling of multiple errors.ignore blocks was unified to prevent type mismatch panics during dependency evaluation. These changes ensure that complex configurations can be rendered to disk or passed between dependencies without intermittent failures.

Operators using the download_dir attribute should verify that their cache paths are either hidden (starting with a dot) or located outside the module source tree to avoid the new error check. The deep_merge function and the auth optimization flag both require explicit opt in via the experimental framework. As these are experimental features, the underlying implementation or CLI flags may change in future releases based on community feedback.