tofu-plan

Generate and show the execution plan in the currently directory

$ tofu plan

$ tofu plan -destroy

$ tofu plan -refresh-only

$ tofu plan -var '[name1]=[value1]' -var '[name2]=[value2]'

$ tofu plan -target [resource_type.resource_name[instance index]]

$ tofu plan -json

$ tofu plan -no-color > [path/to/file]

tofu plan [options] [DIR | PLAN_FILE]

DIR
    The path to a directory containing OpenTofu configuration files. Defaults to the current working directory.

PLAN_FILE
    The path to a previously saved plan file (generated with -out) that should be inspected or applied later.

-compact-warnings
    Show warnings in a more concise form, suppressing details for common warnings.

-destroy
    Generates a plan to destroy all OpenTofu-managed infrastructure. Use with extreme caution.

-detail-exitcode
    Return a detailed exit code: 0 for no changes, 1 for error, 2 for changes detected (when used without -out).

-input=true|false
    Ask for input if variables are not otherwise satisfied. Defaults to true in interactive sessions.

-json
    Output the plan in a machine-readable JSON format, useful for programmatic analysis.

-lock=true|false
    Lock the state file during the planning operation to prevent concurrent modifications. Defaults to true.

-lock-timeout=DURATION
    Duration to retry acquiring a state lock. Format like '30s' or '5m'.

-no-color
    Disable colored output from the plan, useful for logging or non-TTY environments.

-out=PATH
    Save the generated execution plan to a specified file path. This plan can then be applied with tofu apply PATH.

-parallelism=N
    Limit the number of concurrent operations OpenTofu can perform while planning.

-refresh=true|false
    Update the state file with the current real-world infrastructure before planning. Defaults to true.

-state=PATH
    Path to the state file to use for the plan. Defaults to terraform.tfstate in the working directory.

-target=RESOURCE
    Target a specific resource or module for planning. Can be specified multiple times. Use with caution as it can lead to state drift.

-var 'key=value'
    Set a variable value directly. Can be specified multiple times.

-var-file=PATH
    Load variable definitions from a specified file. Can be specified multiple times.

The command tofu plan is a core component of OpenTofu, an open-source infrastructure as code (IaC) tool. It creates an execution plan, which outlines the actions OpenTofu will take to reconcile your infrastructure with the desired state defined in your .tf configuration files.

Before applying any changes, tofu plan performs a 'dry run' by comparing the current state of your managed infrastructure (stored in the state file) against your configuration. The output details exactly which resources will be added (+), changed (~), or destroyed (-), along with specific attribute modifications.

This command is crucial for reviewing potential infrastructure changes, preventing unintended modifications, and ensuring that the proposed operations align with your expectations. It does not modify any real infrastructure; its purpose is solely to generate and display the proposed changes. The generated plan can optionally be saved to a file for later application using tofu apply.

Not a Standard Linux Command: tofu plan is a subcommand of the tofu executable, which is an application-specific command for OpenTofu, not a general-purpose Linux utility like ls or grep.

Requires Initialization: The working directory must be initialized with tofu init before running tofu plan.

State Drift: A saved plan reflects the state at the time of its creation. If external changes occur to your infrastructure or configuration between plan generation and application, the saved plan might become outdated, leading to unexpected results.

'-destroy' Irreversible: The -destroy option generates a plan to tear down all infrastructure. Applying such a plan is largely irreversible and should be used with extreme care.

The output of tofu plan uses specific symbols to indicate actions: + for creation, ~ for in-place updates, and - for destruction. Detailed descriptions for attribute changes, such as (forces replacement) or (changes in-place), are also provided to give a clear understanding of the impact of each change.

One of OpenTofu's core principles is idempotency. Running tofu plan multiple times with the same configuration against the same state should produce an identical plan (or no changes) as long as no external modifications occur to the infrastructure. This consistency ensures predictable outcomes.

tofu plan is frequently integrated into Continuous Integration/Continuous Delivery (CI/CD) pipelines. This allows automated 'dry runs' of infrastructure changes on every code commit, providing early feedback and requiring explicit approval before changes are applied to production environments, thus enhancing reliability and security.

The plan command has been a foundational element of Terraform since its inception, providing a critical preview step in Infrastructure as Code (IaC) workflows. OpenTofu emerged in August 2023 as a community-driven, open-source fork of Terraform, specifically maintaining the Apache 2.0 license after HashiCorp changed Terraform's license. The tofu plan command in OpenTofu retains full feature and behavioral parity with its Terraform counterpart, ensuring a seamless transition and continuity for users. Its development continues under the Linux Foundation's governance, focusing on stability, community contributions, and vendor neutrality.

tofu apply(1), tofu init(1), tofu show(1), tofu validate(1)