Active Experiments

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

`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 both catalog cloning and OpenTofu/Terraform source cloning by avoiding redundant downloads of Git repositories.

`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.

`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)

`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

`filter-flag`

Support for sophisticated unit and stack filtering using the --filter flag.

`filter-flag` - What it does

The --filter flag provides a sophisticated querying syntax for targeting units and stacks in Terragrunt commands. This unified approach replaces the need for multiple queue control flags and offers powerful filtering capabilities.

Current Support Status:

Available in find, list, and run commands

Supported Filtering Types:

Name-based filtering: Target units/stacks by their directory name (exact match or glob patterns)
Path-based filtering: Target units/stacks by their file system path (relative, absolute, or glob patterns)
Attribute-based filtering: Target units by configuration attributes:
- type=unit or type=stack - Filter by component type
- external=true or external=false - Filter by whether the unit/stack is an external dependency (outside the current working directory)
- name=pattern - Filter by name using glob patterns
Negation filters: Exclude units using the ! prefix
Filter intersection: Combine filters using the | operator for results pruning
Multiple filters: Specify multiple --filter flags to union results

Not Yet Implemented:

Git-based filtering ([ref...ref] syntax)
Dependency/dependent traversal (... syntax)

`filter-flag` - How to provide feedback

Provide your feedback on the Filter Flag RFC GitHub issue.

`filter-flag` - Criteria for stabilization

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

Future Deprecations:

When this experiment stabilizes, the following queue control flags will be deprecated in favor of the unified --filter flag:

--queue-exclude-dir
--queue-excludes-file
--queue-exclude-external
--queue-include-dir
--queue-include-external
--queue-include-units-including
--queue-strict-include

The current plan is to continue to support the flags as aliases for particular --filter patterns.

`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

`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 GitHub Discussions page.

`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 a terragrunt.autoinclude.hcl file during stack generation. This file is automatically merged into the unit/stack configuration when parsed.

This experiment enables:

unit.<name>.path and stack.<name>.path variables in terragrunt.stack.hcl for referencing sibling component paths
stack.<name>.<unit_name>.path for referencing individual units within a nested stack (fine-grained dependency)
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 blocks 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 units within a nested stack

stack "stack_w_outputs" {
  source = "../catalog/stacks/stack-w-outputs"
  path   = "stack-w-outputs"
}

unit "unit_w_inputs" {
  source = "../catalog/units/unit-w-inputs"
  path   = "unit-w-inputs"

  autoinclude {
    dependency "unit_w_outputs" {
      config_path = stack.stack_w_outputs.unit_w_outputs.path

      mock_outputs_allowed_terraform_commands = ["plan"]
      mock_outputs = {
        val = "fake-val"
      }
    }

    inputs = {
      val = dependency.unit_w_outputs.outputs.val
    }
  }
}

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

`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

cas

cas - What it does

cas - How to provide feedback

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

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

filter-flag

filter-flag - What it does

filter-flag - How to provide feedback

filter-flag - Criteria for stabilization

iac-engine

iac-engine - What it does

iac-engine - How to provide feedback

iac-engine - 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