Active Experiments

The following experiments are available for opt-in. See the experiments overview for how to enable them.

`azure-backend`

Experimental support for the Azure Storage (azurerm) remote state backend.

`azure-backend` - What it does

Terragrunt already recognizes backend = "azurerm" in remote_state blocks regardless of whether this experiment is enabled, and currently falls through to the native OpenTofu/Terraform azurerm backend. This experiment reserves the flag for the long-term goal of having Terragrunt manage Azure Storage accounts, blob containers, and state blobs in the same way it already manages S3 buckets and GCS buckets: automatic bootstrap, delete, migrate, and direct state reads for dependency-fetch-output-from-state.

In its current form (initial registration) the experiment only:

Reserves the azure-backend experiment name.
Reserves the azurerm backend slot in Terragrunt’s remote state layer.

The flag itself currently has no behavioral effect: there is no Azure SDK code, authentication logic, or storage account management yet, and the backend is not gated on the flag. Functional behavior will land in subsequent releases.

`azure-backend` - How to enable it

# Via CLI flag
terragrunt --experiment azure-backend run -- plan

# Via environment variable
export TG_EXPERIMENT=azure-backend
terragrunt run -- plan

`azure-backend` - How to provide feedback

Track and discuss this experiment in gruntwork-io/terragrunt#4307. When reporting issues or providing feedback, please include:

The Azure authentication method you are using (Azure AD, MSI, service principal, SAS, access key).
The cloud environment (public, government, china).
Any errors encountered during init, plan, or backend bootstrap.

`azure-backend` - Criteria for stabilization

To transition the azure-backend feature to a stable release, the following must be addressed, at a minimum:

internal/azurehelper package wrapping the Azure SDK with a builder pattern matching awshelper/gcphelper.
Bootstrap of storage accounts and blob containers, including versioning and optional RBAC role assignment for use_azuread_auth.
Delete and migrate operations for state blobs and containers with confirmation prompts.
Direct state file reads from Azure blobs for --dependency-fetch-output-from-state.
Documentation covering authentication methods, configuration keys, and troubleshooting.
Integration test coverage gated behind a build tag.
Community feedback on real-world usage.

`cas`

Support for Terragrunt Content Addressable Storage (CAS).

`cas` - What it does

Allow Terragrunt to store and retrieve Git repositories from a Content Addressable Storage (CAS) system.

The CAS is used to speed up catalog cloning, OpenTofu/Terraform source cloning, and stack generation by avoiding redundant downloads of Git repositories. When used with stacks, it also allows catalog authors to use relative paths in source attributes via the update_source_with_cas attribute.

`cas` - How to provide feedback

Share your experience with this feature in the CAS Feedback GitHub Discussion. Feedback is crucial for ensuring the feature meets real-world use cases. Please include:

Any bugs or issues encountered (including logs or stack traces if possible).
Suggestions for additional improvements or enhancements.

`cas` - Criteria for stabilization

To transition the cas feature to a stable release, the following must be addressed:

Add support for storing and retrieving catalog repositories from the CAS.
Add support for storing and retrieving OpenTofu/Terraform modules from the CAS.
Add support for storing and retrieving Unit/Stack configurations from the CAS.

`catalog-redesign`

Redesigned terragrunt catalog TUI with whole-repository discovery, tabbed browsing, and an interactive scaffolding form.

`catalog-redesign` - What it does

Replaces the existing terragrunt catalog experience with a redesigned TUI that removes the need for manual configuration. The new catalog discovers modules and templates across the whole repository, lets you browse them in tabbed views, and scaffolds a selected component through an interactive form.

Discovery walks the entire repository instead of only a modules/ directory, so modules and templates can live anywhere. Boilerplate templates are discovered as a distinct component kind alongside OpenTofu/Terraform modules and labeled as templates in the UI. Catalog authors can commit a .terragrunt-catalog-ignore file at the repo root to exclude directories such as examples/ or test/ from discovery. See Excluding paths from discovery for the supported pattern syntax.

The list view is split into All, Modules, and Templates tabs with All selected by default. Press tab and shift+tab to cycle between them; each tab keeps its own cursor and search filter.

Each list entry shows a metadata row with a component-type pill (module, template), the source URL it was discovered from, and a version pill when a release tag is available, so it is clear which repository or path a component came from.

Pressing s on a selected component opens an in-TUI form that prompts for every variable the component exposes (.tf variable blocks for modules and templates, values.* references for units and stacks). The form is modal: j/k (or arrows) navigate between fields, enter enters edit mode on a text field or toggles a boolean checkbox in place, esc returns from edit to navigate, x marks an optional field “use default” so it’s left out of the generated file, ctrl+d finishes, and esc from navigate cancels back to the catalog. Only fields the user explicitly sets are written to the generated terragrunt.hcl or terragrunt.values.hcl; required fields the user never set still produce # TODO: fill in value placeholders. Pressing S (capital) keeps the original placeholder-only flow for users who want to populate values by editing the generated file.

`catalog-redesign` - How to provide feedback

Provide your feedback on the catalog-redesign GitHub Discussion.

`catalog-redesign` - Criteria for stabilization

To transition the catalog-redesign feature to a stable release, the following must be addressed:

Multiple catalog browse views (All, Modules, Templates tabs) are implemented and functional.
Catalog launches without requiring manual configuration (no pre-existing catalog block needed).
Discovery walks the entire repository, surfacing modules and boilerplate templates wherever they live.
Authors can exclude paths from discovery with a .terragrunt-catalog-ignore file.
Component source is visible in the UI for each catalog entry.
Component type (module, unit, stack, template) is clearly indicated in the UI.
An interactive scaffold form prompts for each variable a component exposes and generates terragrunt.hcl/terragrunt.values.hcl.
Integration tests cover the core catalog workflows.
Positive feedback from users using the redesigned catalog in production environments.

`dag-queue-display`

Display the run queue as a DAG tree showing dependency hierarchy.

`dag-queue-display` - What it does

By default, Terragrunt displays the run queue as a flat list of units before execution. When this experiment is enabled, the queue is rendered as a tree that visualizes dependency relationships between units. Independent units appear as siblings at the root, while dependent units are nested under their dependencies.

The tree also changes its header message based on execution direction:

Apply/Plan: “starting with dependencies and then their dependents”
Destroy: “starting with dependents and then their dependencies”

terragrunt run --all --experiment dag-queue-display -- plan

Example output:

The following units will be run, starting with dependencies and then their dependents:
.
├── monitoring
╰── vpc
    ╰── database
        ╰── backend-app
            ╰── frontend-app

`dag-queue-display` - How to provide feedback

Provide your feedback on the DAG Queue Display GitHub Discussion.

`dag-queue-display` - Criteria for stabilization

To transition the dag-queue-display feature to a stable release, the following must be addressed, at a minimum:

Community feedback on the tree visualization format
Confirm readability with large dependency graphs
Confirm compatibility with CI/CD log viewers (color and Unicode handling)

`deep-merge`

Support for the deep_merge HCL function.

`deep-merge` - What it does

When enabled, Terragrunt exposes a deep_merge(map1, map2, ...) HCL function for combining map or object values.

For overlapping keys, values from later arguments override earlier arguments. Nested maps are merged recursively, lists are appended, and null arguments are ignored.

This is useful when building inputs from multiple JSON, YAML, or HCL-derived maps without having to rely on include block merge behavior.

terragrunt run --all --experiment deep-merge -- plan

`deep-merge` - How to provide feedback

Provide your feedback in the deep-merge GitHub Discussion.

`deep-merge` - Criteria for stabilization

To transition the deep-merge feature to a stable release, the following must be addressed:

Confirm the merge semantics are useful for common configuration layering workflows.
Confirm type handling for decoded JSON/YAML and native HCL objects matches user expectations.
Positive feedback from users relying on the function in production pipelines.

`dependency-fetch-output-from-state`

Support for fetching dependency outputs directly from state files.

`dependency-fetch-output-from-state` - What it does

By default, Terragrunt retrieves dependency outputs by running tofu output or terraform output commands, which requires initializing the dependency unit and can be slow. When this experiment is enabled, Terragrunt will attempt to fetch dependency outputs directly from the remote state file, bypassing the need to initialize the dependency and significantly speeding up dependency processing.

Current Backend Support:

S3 backend: Fully supported
Other backends: Falls back to the normal method (using tofu/terraform output)

When an unsupported backend is encountered, Terragrunt will automatically fall back to the default method of using tofu/terraform output.

Known Limitations:

This experiment is not compatible with OpenTofu state encryption. When OpenTofu’s client-side state encryption is enabled, the state file stored in S3 is encrypted before upload. Since this experiment reads the raw state file directly from S3 via the AWS SDK, it cannot decrypt the state and will fail with a JSON parsing error. If you are using OpenTofu state encryption, you must disable this experiment using the --no-dependency-fetch-output-from-state flag.

Disabling the feature:

You can disable the dependency-fetch-output-from-state feature using the --no-dependency-fetch-output-from-state flag, even when the experiment is enabled:

terragrunt run --all --experiment-mode --no-dependency-fetch-output-from-state -- plan

`dependency-fetch-output-from-state` - How to provide feedback

Provide your feedback in the dedicated GitHub discussion page. When reporting issues or providing feedback, please include:

The backend type you’re using
Any performance improvements you’ve observed
Any issues or edge cases you’ve encountered

`dependency-fetch-output-from-state` - Criteria for stabilization

To transition the dependency-fetch-output-from-state feature to a stable release, the following must be addressed, at a minimum:

Add support for additional backends (e.g., GCS, etc.)
Comprehensive integration testing across different backend types
Performance benchmarking to validate speed improvements
Error handling and edge case testing
Documentation of supported backends and limitations
Handle OpenTofu state encryption gracefully (fallback or explicit error message)
Community feedback on real-world usage

`iac-engine`

Support for Terragrunt IaC engines.

`iac-engine` - What it does

Enables usage of Terragrunt IaC engines for running IaC operations. This allows Terragrunt to use pluggable engines to execute Terraform/OpenTofu commands, providing enhanced functionality and extensibility.

IaC engines are still experimental, as the API is unstable and may change in future minor versions of Terragrunt.

You can disable engine usage on a per-command basis using the --no-engine flag, even when the experiment is enabled globally.

`iac-engine` - How to provide feedback

Provide your feedback on the Terragrunt IaC Engines GitHub discussion.

`iac-engine` - Criteria for stabilization

To transition the iac-engine feature to a stable release, the following must be addressed, at a minimum:

API stability and backward compatibility guarantees
Comprehensive integration testing across all supported operations
Documentation of engine development and integration process
Performance benchmarks and optimization
Security review of engine execution and isolation mechanisms
Community feedback on real-world usage and edge cases

`mark-many-as-read`

Mark many files as read in one step, so reading-based filter expressions cascade changes from shared files to the units that consume them.

`mark-many-as-read` - What it does

Enabling the experiment activates two behaviors:

When a unit’s terraform block points at a local module source, Terragrunt walks that directory and records every *.tf, *.tf.json, *.hcl, *.tofu, and *.tofu.json file as read for the unit. Non-source files such as README.md are skipped. Remote sources (Git, registry, S3, etc.) are not walked.
The mark_glob_as_read(pattern) HCL function becomes available. It expands a glob using gobwas/glob syntax and marks every matching file as read, returning the list of absolute paths that matched. Without the experiment enabled, calling the function returns an error. See the HCL reference for pattern syntax and examples.

Both behaviors feed the same reading tracker that powers the reading= filter attribute, so a change to a local module file or a globbed configuration file is picked up by --filter 'reading=<path>' and matches every unit that reads it.

terragrunt run --all --experiment mark-many-as-read -- plan

`mark-many-as-read` - How to provide feedback

Provide your feedback on the mark-many-as-read GitHub Discussion.

`mark-many-as-read` - Criteria for stabilization

To transition the mark-many-as-read feature to a stable release, the following must be addressed:

Confirm local module walking handles nested modules sensibly across macOS, Linux, and Windows.
Confirm glob semantics match user expectations for common patterns, especially ** with a wildcard trailing segment.
Positive feedback from users relying on reading-based filters in production pipelines.
Integration tests covering the interaction between module walking, mark_glob_as_read, and --filter 'reading=...'.

`opt-out-auth`

Opt out of running --auth-provider-cmd during the discovery phase.

`opt-out-auth` - What it does

By default, Terragrunt runs --auth-provider-cmd once per parsed component during the discovery phase, so configuration parsing can reliably resolve HCL functions such as get_aws_account_id and run_cmd. On large repositories, this dominates wall-clock time because the auth command runs for every discovered unit rather than only the subset that will actually run.

Enabling this experiment unlocks the --no-discovery-auth-provider-cmd flag (env: TG_NO_DISCOVERY_AUTH_PROVIDER_CMD), which skips those discovery-time auth invocations. The auth provider command still runs normally for the units that actually execute.

Units whose discovery-relevant blocks depend on credentials produced by --auth-provider-cmd will fail to parse with the flag set. Use it when you know parsing will resolve successfully without any prior authentication.

terragrunt run --all \
  --experiment opt-out-auth \
  --no-discovery-auth-provider-cmd \
  --queue-include-units-reading=./changed-file.txt \
  plan

`opt-out-auth` - How to provide feedback

Provide your feedback on the opt-out-auth GitHub Discussion.

`opt-out-auth` - Criteria for stabilization

To transition the opt-out-auth feature to a stable release, the following must be addressed, at a minimum:

Confirm the discovery-phase opt-out covers the auth scenarios users rely on without surprising parse failures.
Measure the wall-clock improvement on large run --all invocations with reading-based filters.
Decide whether additional phases warrant their own opt-out flags.
Community feedback on real-world usage.

`slow-task-reporting`

Progress reporting for long-running Terragrunt operations.

`slow-task-reporting` - What it does

When enabled, Terragrunt displays animated progress spinners for operations that take longer than 1 second (e.g., Git worktree creation). Once the operation completes, the spinner is replaced with an INFO log line showing the operation result and elapsed time.

This provides visual feedback during operations that would otherwise show no output:

Git worktree creation for --filter with Git references
Catalog repository cloning (terragrunt catalog)
OpenTofu/Terraform source downloads via go-getter

In non-interactive environments (CI/CD, piped output), spinners are suppressed and INFO log lines are emitted instead. To prevent CI systems (e.g., CircleCI) from killing jobs due to prolonged output silence, periodic keepalive log lines are emitted every 30 seconds while the operation is in progress.

terragrunt run --all --experiment slow-task-reporting -- plan

`slow-task-reporting` - How to provide feedback

Provide your feedback on the slow-task-reporting GitHub Discussion.

`slow-task-reporting` - Criteria for stabilization

To transition the slow-task-reporting feature to a stable release, the following must be addressed:

Validate spinner rendering across common terminal emulators (iTerm2, Terminal.app, Windows Terminal, GNOME Terminal)
Extend progress reporting to additional slow operations (e.g., provider caching)
Community feedback on usefulness and threshold tuning
Ensure no interference with structured log output when using --log-format json

`stack-dependencies`

Support for the autoinclude block in terragrunt.stack.hcl files, enabling dependency relationships and configuration overrides during stack generation.

`stack-dependencies` - What it does

When enabled, this experiment adds support for the autoinclude block nested inside unit and stack blocks in terragrunt.stack.hcl files. The autoinclude block allows users to define dependency blocks and arbitrary configuration that gets generated into an autoinclude file during stack generation. This file is automatically merged into the unit/stack configuration when parsed.

The generated filename depends on the component kind:

Unit autoincludes are written as terragrunt.autoinclude.hcl next to the unit’s terragrunt.hcl.
Stack autoincludes are written as terragrunt.autoinclude.stack.hcl next to the nested stack’s terragrunt.stack.hcl. The .stack.hcl suffix mirrors terragrunt.stack.hcl so tooling (LSP, read_terragrunt_config(), indexers) can identify the file’s purpose from its name alone.

This experiment enables:

unit.<name>.path and stack.<name>.path variables for referencing sibling component paths, both inside autoinclude blocks and in a unit or stack block’s values (so a parent stack can pass a component path down to a child stack)
dependency blocks targeting stack directories: aggregated outputs from all units in the stack (dependency.stack_name.outputs.unit_name.output_key)
Automatic deep merge of terragrunt.autoinclude.hcl into unit configurations (autoinclude wins)
Stack dependency expansion in the run queue: depending on a stack waits until all its units complete

Unit-to-unit dependencies within a stack

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
    }
  }
}

Dependencies on entire stacks

stack "infra" {
  source = "../catalog/stacks/infra"
  path   = "infra"
}

unit "app" {
  source = "../catalog/units/app"
  path   = "app"

  autoinclude {
    dependency "infra" {
      config_path = stack.infra.path
    }

    inputs = {
      vpc_id = dependency.infra.outputs.vpc.vpc_id
    }
  }
}

terragrunt run --all --experiment stack-dependencies -- plan

`stack-dependencies` - How to provide feedback

Provide your feedback on the Stack Dependencies RFC GitHub Issue.

`stack-dependencies` - Implementation roadmap

Phased parser for terragrunt.stack.hcl: parse the file body, evaluate locals and values, apply include merges, then decode unit/stack blocks and resolve autoinclude. This lets unit/stack blocks use local.*, values.*, and Terragrunt functions.
terragrunt run --all discovery can scan generated nested stack files without evaluating the unit source.
Unify strict and permissive parser into a single code path
Add integration tests and test fixtures for end-to-end validation
Add E2E validation with stack run apply and stack run destroy

Catalog source preservation across stack copy: nested stack files copied into .terragrunt-stack/<name>/ get a .terragrunt-stack-origin marker file, so bare relative ../../units/... paths resolve against the original catalog, not the copy. Only applies to local stack sources; remote and CAS-fetched stacks are unchanged.
PartialEval depth guard (maxPartialEvalDepth = 10000) and IsWhollyKnown / IsNull checks on the fast path and traversal/template/conditional/parens branches, preventing crashes on unknown values or pathological nesting.
Typed errors with Unwrap() across the package (FileParseError, FileDecodeError, IncludeValidationError, LocalEvalError, MalformedDependencyError, AutoIncludeParserStageError) preserving hcl.Diagnostics for source positions.
Deterministic cycle reports in LocalsCycleError.Names (DFS dep iteration sorted).
resolveStackFilePath returns (string, bool): callers branch on isStackCandidate instead of a sentinel empty string. Backed by a two-arg fuzz that exercises raw/target independently.
Removed Unicode from internal/hclparse source files (ASCII-only); intentional Unicode test fixtures remain.

`symlinks`

Support symlink resolution for Terragrunt units.

`symlinks` - What it does

By default, Terragrunt will ignore symlinks when determining which units it should run. By enabling this experiment, Terragrunt will resolve symlinks and add them to the list of units being run.

`symlinks` - How to provide feedback

Provide your feedback on the Experiment: Symlinks discussion.

`symlinks` - Criteria for stabilization

To stabilize this feature, the following need to be resolved, at a minimum:

Ensure that symlink support continues to work for users referencing symlinks in flags. See #3622.
- Add integration tests for all filesystem flags to confirm support with symlinks (or document the fact that they cannot be supported).
Ensure that MacOS integration tests still work. See #3616.
- Add integration tests for MacOS in CI.

Active Experiments

azure-backend

azure-backend - What it does

azure-backend - How to enable it

azure-backend - How to provide feedback

azure-backend - Criteria for stabilization

cas

cas - What it does

cas - How to provide feedback

cas - Criteria for stabilization

catalog-redesign

catalog-redesign - What it does

catalog-redesign - How to provide feedback

catalog-redesign - Criteria for stabilization

dag-queue-display

dag-queue-display - What it does

dag-queue-display - How to provide feedback

dag-queue-display - Criteria for stabilization

deep-merge

deep-merge - What it does

deep-merge - How to provide feedback

deep-merge - Criteria for stabilization

dependency-fetch-output-from-state

dependency-fetch-output-from-state - What it does

dependency-fetch-output-from-state - How to provide feedback

dependency-fetch-output-from-state - Criteria for stabilization

iac-engine

iac-engine - What it does

iac-engine - How to provide feedback

iac-engine - Criteria for stabilization

mark-many-as-read

mark-many-as-read - What it does

mark-many-as-read - How to provide feedback

mark-many-as-read - Criteria for stabilization

opt-out-auth

opt-out-auth - What it does

opt-out-auth - How to provide feedback

opt-out-auth - Criteria for stabilization

slow-task-reporting

slow-task-reporting - What it does

slow-task-reporting - How to provide feedback

slow-task-reporting - Criteria for stabilization

stack-dependencies

stack-dependencies - What it does