Changelog
This page tracks notable changes to Terragrunt. For the full list of releases and their assets, see the GitHub Releases Page.
v1.0.1
🧪 Experiments Added
dag-queue-display — DAG tree visualization for the run queue
A new dag-queue-display experiment renders the run queue as a dependency tree instead of a flat list, making it easier to understand execution order and dependency relationships at a glance.
$ terragrunt run --all --experiment dag-queue-display -- plan19:06:59.108 INFO The following units will be run, starting with dependencies and then their dependents:.├── monitoring╰── vpc ╰── database ╰── backend-app ╰── frontend-appTo learn more, see the experiment documentation.
slow-task-reporting — Progress reporting for long-running operations
A new slow-task-reporting experiment displays animated progress spinners for operations that take longer than 1 second, such as source downloads, Git worktree creation, and catalog repository cloning. In non-interactive environments (CI/CD, piped output), spinners are replaced with periodic INFO log lines every 30 seconds to prevent CI systems from killing jobs due to output inactivity.
$ terragrunt run --all --experiment slow-task-reporting -- planINFO Downloading source from git::https://github.com/example/module.git...INFO Downloaded source from git::https://github.com/example/module.git (3.2s)To learn more, see the experiment documentation.
stack-dependencies — Dependency wiring between units in stacks
A new stack-dependencies experiment enables the autoinclude block in terragrunt.stack.hcl files, allowing units and stacks to define dependency relationships and arbitrary configuration overrides during stack generation. This implements RFC #5663.
unit "vpc" { source = "../catalog/units/vpc" path = "vpc"}
unit "app" { source = "../catalog/units/app" path = "app"
autoinclude { dependency "vpc" { config_path = unit.vpc.path }
inputs = { vpc_id = dependency.vpc.outputs.vpc_id } }}terragrunt run --all --experiment stack-dependencies -- planTo learn more, see the experiment documentation.
💡 Tip Added
Windows symlink warning for provider cache users
Terragrunt now warns Windows users when symlink creation fails and provider caching is enabled. OpenTofu and Terraform may silently fall back to copying provider plugins instead of symlinking, which can increase disk usage and slow down operations. For OpenTofu >= 1.12.0, the tip includes guidance on using TF_LOG=warn to detect the fallback.
Thank you to the OpenTofu team for introducing this warning to ensure that Windows users are aware of the fallback behavior.
🐛 Bug Fixes
hcl validate no longer fails on dependency.outputs references
terragrunt hcl validate previously failed with “Unsupported attribute” when a configuration referenced dependency.<name>.outputs.<key> without mock_outputs.
During validation, output resolution is skipped, but the outputs attribute was never added to the dependency evaluation context, causing any output reference to error. The fix provides a dynamic placeholder for dependency outputs (and inputs) during validation so that attribute access evaluates to unknown rather than failing. Additionally, the dependency resolution pipeline is now more resilient during validation. Dependencies with unresolvable config_path values or nonexistent targets no longer cause the entire dependency namespace to disappear from the evaluation context.
Destroy queue now displays units in correct order
Previously, the run queue display showed units in apply order even for destroy commands. The queue now correctly shows dependents before their dependencies when running destroy, matching the actual execution order.
Dependent discovery fixed in worktrees
Dependents are now correctly discovered when units are discovered in worktrees. Previously, dependent discovery could fail to find related units when operating within a git worktree.
Filter exclusions now respected in worktree sub-discoveries
Negated filters (e.g., !./catalog/** from .terragrunt-filters or --filter) are now propagated to worktree sub-discoveries used by git-based filtering (--filter-affected, --filter '[ref...ref]').
Previously, excluded source catalog units in worktrees were still discovered and parsed, causing errors when they referenced values.* or dependency.* variables without the stack generation context.
read_terragrunt_config() behavior in implicit stacks fixed
A regression introduced in v0.99.4 caused read_terragrunt_config() to fail to parse dependency blocks in external configurations during stack execution. This is fixed by resetting parsing context fields that prevented proper evaluation of dependencies in configurations read by read_terragrunt_config().
get_original_terragrunt_dir() now resolves correctly during dependency parsing
A regression introduced in v1.0.0-rc3 caused get_original_terragrunt_dir() to return the dependent directory instead of the dependency’s directory when parsing dependency configurations from a unit.
This broke configurations where a dependency’s read_terragrunt_config() chain relied on get_original_terragrunt_dir() to locate sibling files. The fix introduces a dedicated WithDependencyConfigPath method that correctly resets the original config path when parsing a dependency as an independent unit.
Chained dependency with exposed include conversion fixed
Chaining dependencies with exposed includes no longer produces a spurious “Could not convert include to the execution ctx to evaluate additional locals” error during partial parsing.
Provider cache fixed on Windows for remote URLs
The provider cache failed on Windows with CreateFile https://...: The filename, directory name, or volume label syntax is incorrect because remote download URLs were passed to os.Stat, and the colon in https: is invalid Windows path syntax. The fix skips the filesystem existence check when the download URL is a remote URL (://), going directly to the download path.
Additional transient network errors now retried automatically
Added retry patterns for provider resolution and registry connection failures commonly seen in CI environments, including TLS handshake timeouts, TCP connection resets, context deadline exceeded errors, and failed discovery document requests. These cover both Terraform and OpenTofu provider workflows.
⚙️ Process Updates
Tip builds now available from main
Every successful CI run on the main branch now automatically produces tip build binaries with signed checksums for all supported platforms (Windows and macOS binaries are not codesigned in tip builds). These builds are accessible via the builds API at https://builds.terragrunt.com — see the releases process documentation for API endpoints and usage examples. Maintainers can also trigger on-demand test builds from any branch using the test-build.yml workflow.
Concurrency limits now respect GOMAXPROCS
All internal concurrency limits now use runtime.GOMAXPROCS(0) instead of runtime.NumCPU(). This means Terragrunt correctly honors the GOMAXPROCS environment variable and container CPU quotas (e.g., cgroups), resulting in better behavior in resource-constrained environments like Kubernetes pods and CI runners with CPU limits.
AWS SDK updated to v1.41.5
The aws-sdk-go-v2 dependency has been updated to v1.41.5.
Terragrunt Scale documentation added
A new Terragrunt Scale section has been added to the docs, covering Pipelines, Drift Detection, and Patcher with brief overviews and links to the full Gruntwork documentation.
v1.0.0
🛠️ Breaking Changes
Consistent .terragrunt-cache directory generation
Terragrunt now creates a .terragrunt-cache directory for every run, regardless of whether the terragrunt.hcl file defines a terraform block with a source attribute.
This change improves consistency across all Terragrunt executions, as OpenTofu/Terraform will now always run within the .terragrunt-cache directory. This standardized behavior simplifies troubleshooting and makes the execution model more predictable.
Removal of tflint
Terragrunt has been shipping with a version of tflint compiled into the binary to allow for more convenient usage without installing tflint directly. However due to the adoption of a BUSL license in tflint, the version included in Terragrunt was frozen.
The dependency on tflint is now fully removed from Terragrunt. If you want to call tflint using a before_hook using Terragrunt, you will have to have tflint installed locally to do so.
To reduce the burden of this breaking change, Terragrunt will continue to provide conveniences like automatically running tflint init on behalf of users, although it no longer ships with a compiled version of tflint in the terragrunt binary.
To learn more, read the documentation on the integration with tflint.
Discovery commands discover hidden configurations by default
The find and list commands now discover units/stacks in hidden directories by default (this previously required usage of the --hidden flag), notably this now discovers .terragrunt-stack directories by default. The commands also now support an opt-in --no-hidden flag to avoid discovery in hidden directories.
The --hidden flag has been deprecated, and will not be removed in 1.0. Using the flag no longer does anything.
render --format=json no longer discovers dependents by default
Prior to this release, the render --format=json command would automatically start to perform dependent discovery on other units related to the unit being rendered. Avoiding this required usage of the --disable-dependent-modules flag. That behavior has been removed. HCL and JSON rendering of unit configurations will now proceed without the additional overhead of dependent discovery by default.
This functionality is better served by a combination of find and graph-based filters.
e.g. If you want to detect all the dependents of a given unit foo, expecting to find the dependent unit bar you can run the following:
$ terragrunt find --filter '...^foo'barIf you aren’t familiar with filters, this reads as “find all dependents of foo, not foo itself”
Windows compatibility in file paths improved
All HCL functions now return operating system native file paths without forward slash normalization.
get_terragrunt_dir()get_original_terragrunt_dir()get_parent_terragrunt_dir()get_path_from_repo_root()get_path_to_repo_root()find_in_parent_folders()path_relative_to_include()path_relative_from_include()
If you and your team do not work in Windows environments, you are unlikely to see any change as a consequence of this. If you do use Terragrunt in a Windows environment, Terragrunt will now return appropriate Windows file paths, with backslashes as file path separators instead of Unix-like forward slashes.
If you need to normalize paths, you can use the replace function to achieve this.
remote_state { backend = "s3"
generate = { path = "backend.tf" if_exists = "overwrite_terragrunt" }
config = { bucket = "my-tofu-state"
key = "${replace(path_relative_to_include(), "\\", "/")}/tofu.tfstate" region = "us-east-1" encrypt = true dynamodb_table = "my-lock-table" }}Ambiguous unit/stack components now throw errors
Previously, Terragrunt would silently engage in undefined behavior when both a terragrunt.hcl and terragrunt.stack.hcl file existed in the same directory.
With this release, Terragrunt will start to throw warnings and prevent such usage. Users will have to ensure that only one of a unit (terragrunt.hcl) or stack configuration (terragrunt.stack.hcl) exist in a unit or stack directory, respectively.
✨ New Features
Tips added
Terragrunt will now provide helpful tips when it detects usage patterns that might benefit from some additional guidance.
You can disable the display of tips at any time using --no-tips or disable individual tips with --no-tip, (e.g. --no-tip=debugging-docs).
--report-file support for single runs
The --report-file will now generate reports even when runs are performed without the --all flag.
Improved error messages for undefined flags
Detection has been added for scenarios when a user is using a flag that might be meant to be passed to OpenTofu/Terraform in the run command, and suggests using the -- argument to pass it through.
As an example:
$ terragrunt run providers lock -platform linux_amd64 -platform darwin_arm6414:52:19.496 ERROR flag `-platform` is not a Terragrunt flag. If this is an OpenTofu/Terraform flag, use `--` to forward it (e.g., `terragrunt run -- <command> -platform`).🏎️ Performance Improvements
Discovery performance improved
The way in which Terragrunt discovers and filters units and stacks for runs has improved significantly.
Terragrunt is now better at avoiding parsing units/stacks unnecessarily, based on the filter you use. Previously, the logic used was more coarse, and could result in a requirement to parse some configurations (e.g. presence of a dependency graph expression) to result in parsing all configurations. Discovery has been refactored to allow for much more careful opt-in parsing based on the need to support the filter used by users (or lack thereof).
This will also result in improvements to Terragrunt’s ability to ignore broken parts of infrastructure estates when Terragrunt can predictably determine that it won’t impact a run.
EncodeSourceVersion execution sped up
The performance of EncodeSourceVersion has been improved by utilizing SkipDir to optimize directory traversals.
Special thanks to @healthy-pod for contributing this improvement!
Provider Cache Server used for fetching outputs from dependencies
The Provider Cache Server is now used when fetching outputs from dependencies, improving performance of output resolution for users using the provider cache server.
🐛 Bug Fixes
Improved filter parsing errors
Parsing errors returned when invalid filter queries are used with --filter have been improved to provide more detailed error messages and actionable recommendations.
Retries added for registry timeouts in provider cache server
The Provider Cache Server will now perform automatic retries on timeouts to OpenTofu/Terraform provider registries.
Discoverability of init-from-module documentation improved
The special internal init-from-module command referenced in hooks has had its documentation improved to make it easier to discover. It was difficult to find in the terraform HCL block documentation, and that resulted in confusion for users.
Over-warning on strict controls prevented
Using --strict-mode resulted in over-warning on completed controls. Those warnings will no longer appear when using strict mode.
Stdout/stderr from run_cmd emitted when included
A bug prevented the run_cmd HCL function from emitting to stdout/stderr when included by a unit. That bug has been fixed.
Provider Cache Server integration with custom registries fixed
The Provider Cache Server now properly integrates with custom registries. You will still need to use the --provider-cache-registry-names flag to ensure that the Provider Cache Server properly handles proxying requests to the custom provider registry.
The no_run attribute of exclude is fixed
A bug prevented the no_run attribute of the exclude block from being respected when being explicitly set to false (as opposed to not being defined at all). This bug has been fixed.
The --report-file is now respected for single runs
The --report-file will now generate reports even when runs are performed without the --all flag.
Path manipulation removed from log messages
Log messages no longer have paths updated automatically. This caused confusion for users when seeing OpenTofu/Terraform stdout and hook stdout emitted through logs, as paths were unconditionally updated to be relative to the unit path. This logic has been moved to logging call sites to ensure that external process stdout/stderr is not manipulated unexpectedly.
Absolute URLs in registry self-discovery integration with Provider Cache Server Fixed
When using the Provider Cache Server in conjunction with a remote registry using absolute URLs for modules, the Provider Cache Server will now properly resolve the module source.
SOPS decryption race condition fixed
A race condition in the concurrent access to SOPS decrypted secrets in different environments combined with usage of the --auth-provider-cmd flag resulted in authentication failures. Synchronization controls have been introduced to ensure authentication proceeds correctly for each environment independently.
Version constraints in stack runs fixed
When running against a stack, a bug prevented Terragrunt + OpenTofu/Terraform version constraints from being respected while using the terragrunt_version_constraint and terraform_version_constraint HCL attributes. That bug has been fixed.
Interrupt signal propagation to OpenTofu/Terraform fixed
The mechanism by which Terragrunt sends interrupt signals to OpenTofu/Terraform processes it started has been made more robust. Terragrunt will now send the interrupt signal in the event that a user explicitly sends an interrupt signal to Terragrunt in addition to scenarios where Terragrunt’s context cancellation is triggered (e.g. in the event of a timeout).
Remote state configuration parsing fixed
Remote state configuration parsing (especially S3) is now more tolerant of common input formats, reducing decode-related failures from type mismatches in configuration values.
Parsing behavior has also been made more consistent across related remote configuration blocks in Terragrunt, with regression tests added to prevent future breakages.
Invalid unit configurations cause explicit errors instead of silently being excluded during runs
A bug in discovery logic resulted in units with invalid HCL configurations being silently excluded from runs with a warning. This bug has been fixed, and attempting to parse invalid HCL configurations during a run will result in an error.
Partial parse configuration cache fixed
A bug affecting the partial parse configuration cache (in use when the --use-partial-parse-config-cache flag is supplied) has been resolved, ensuring configurations are cached and read accurately without incorrect cache collisions.
Engine output adjusted
The display and formatting of engine outputs have been updated to be cleaner and more intuitive for users when running Terragrunt workflows.
Stdout/Stderr entries emitted from engines will now have the engine tool listed instead of tofu.
More accurate matching of retryable errors
Fixes a bug where retries were triggered when an expected error is matched against non-stderr output from external process errors.
Duplicate error reporting fixed
Fixes a bug where duplicate errors were reported when running units through the worker pool subsystem.
Interaction between --working-dir and -detailed-exitcode fixed
Fixes a bug where the wrong cache key was used for storing exit codes for OpenTofu/Terraform runs in units when the --working-dir flag was also used.
Variable sanitization via escaping added
Escaping added for interpolation expressions (e.g. ${foo}) that are unlikely to be desired by users.
Removing usage of filepath.Abs and reducing usage of filepath.ToSlash
Usage of the Golang filepath.Abs and filepath.ToSlash standard library functions significantly reduced. Overly broad application of these functions to file paths caused subtle operating system compatibility issues and incompatibility with the --working-dir flag.
The codebase has been updated to only use filepath.Abs early on in initialization of the CLI prior to setting the value of --working-dir (after which, working dir is considered the source of truth for file path canonicalization) and tests. The codebase has been updated to use filepath.ToSlash only where unix-style forward slash normalization is a requirement (e.g. when used in file path globs).
Handling of backend init when disable_init=true
Fixes a bug where disable_init = true affected behavior beyond Terragrunt’s bootstrap operations. disable_init now correctly limits its scope to Terragrunt bootstrap steps only.
Fix detection of offline usage in Provider Cache Server
A bug in the detection of offline usage in the Provider Cache Server resulted in attempts to reach the default provider registry for OpenTofu/Terraform to trigger errors even when using the Provider Cache Server to proxy requests to a network or filesystem mirror.
This has been fixed. When the default provider registry isn’t available for OpenTofu/Terraform for any reason, the Provider Cache Server will use the provided network/filesystem mirror instead without attempting to use the discovery endpoint. This will help users in air-gapped environments using the Provider Cache Server.
Improved log messages for hooks with errors
Hooks encountering errors will now return errors that better communicate whether an error was caused by failure to execute an external process or successfully running an external process, but receiving a non-zero exit code.
Relative paths in reading files fixed
A bug in the logic for incorporating includes as absolute paths in tracked “read” files has been fixed.
OpenTofu file extensions handled in catalog and scaffold
Terragrunt catalog now lists modules that use .tofu, .tf.json, or .tofu.json files. Terragrunt scaffold now parses variables from .tofu files — previously, variables defined in .tofu files were silently missing from the generated terragrunt.hcl.
Bootstrap use_lockfile boolean handling fixed
A bug in remote state backend configuration caused use_lockfile = true to be emitted as use_lockfile = "true" (quoted string), which OpenTofu/Terraform rejects. Boolean values in backend config are now normalized correctly.
Provider cache lock file corruption fixed
A bug that could cause provider cache lock file corruption has been fixed.
Git filter discovery for read_terragrunt_config fixed
Git-filter discovery now correctly detects stacks affected by changes to sidecar files read via read_terragrunt_config(), by parsing stack files to check FilesRead against diff paths instead of relying on generic directory-based detection.
S3 bucket tagging moved to bucket creation
S3 bucket tagging during backend bootstrapping has been moved to bucket creation. This prevents errors caused when SCPs restrict creation of buckets without appropriate tags.
Windows user input fixed
A bug on Windows caused user input prompts (e.g. for confirming apply) to stop working after subprocess execution. Terragrunt now saves and restores console state around every subprocess execution and re-enables Virtual Terminal processing.
Authentication during queue construction fixed
A bug in the logic for parsing configurations during discovery for use-cases like --filter 'reading=*' where configurations need to be parsed to determine whether or not they end up in the final run queue has been fixed. Configurations will now properly call any configured --auth-provider-cmd authenticator before parsing configurations, preventing errors for HCL functions like sops_decrypt_file that require authentication before parsing can proceed.
hcl fmt on unintended files during scaffold fixed
A bug caused hcl fmt to run on files that weren’t generated by scaffold. Formatting is now scoped to only scaffolded content.
Input precision loss fixed
A bug in the way Terragrunt handled setting of OpenTofu/Terraform inputs from numbers resulted in precision loss. That bug has been fixed.
📖 Documentation Updates
1.0 Guarantees
A living document named Terragrunt 1.0 Guarantees has been added to the Terragrunt website clarifying what is and isn’t considered a breaking change for the duration of 1.0.
Over time, as ambiguity in edge-cases for what is considered a breaking change are addressed, the page will be updated so that you can be confident your workflows won’t be impaired.
llms.txt added
An /llms.txt route has been added to the Terragrunt website to make it easier for LLMs to consume Terragrunt documentation in Markdown format.
New Home for the Terragrunt website!
The Terragrunt website is now hosted at https://terragrunt.com and https://docs.terragrunt.com for marketing and documentation purposes, respectively.
Existing links to https://terragrunt.gruntwork.io should seamlessly redirect to the new domain that hosts the content for that URI.
🧪 Experiments Updated
Engines now use GitHub environment variables for downloads
When downloading engines using the engine experiment, Terragrunt will detect and leverage the GH_TOKEN and GITHUB_TOKEN environment variables if present to authenticate with the GitHub API while performing release discovery and download of engines.
⚙️ Process Updates
Go bumped to v1.26
The version of Golang used to compile the Terragrunt binary has been updated to v1.26.0.
OpenTofu/Terraform Compatibility Updated
Terragrunt is now continuously tested against OpenTofu 1.11.4 and Terraform 1.14.4 in CI.
AWS and GRPC dependencies update
Updated AWS SDK and gRPC dependencies to pick up the latest bug fixes and security patches:
google.golang.org/grpctov1.79.1github.com/aws/aws-sdk-go-v2/configtov1.32.8github.com/aws/aws-sdk-go-v2/credentialstov1.19.8
Prior Releases
For all prior releases, see the GitHub Releases Page.