website/docs/cli/commands/plan.mdx
The tofu plan command creates an execution plan, which lets you preview
the changes that OpenTofu plans to make to your infrastructure. By default,
when OpenTofu creates a plan it:
The plan command alone does not actually carry out the proposed changes You can use this command to check whether the proposed changes match what
you expected before you apply the changes or share your changes with your
team for broader review.
If OpenTofu detects that no changes are needed to resource instances or to
root module output values, tofu plan will report that no actions need
to be taken.
If you are using OpenTofu directly in an interactive terminal and you expect
to apply the changes OpenTofu proposes, you can alternatively run
tofu apply directly. By default, the "apply" command
automatically generates a new plan and prompts for you to approve it.
You can use the optional -out=FILE option to save the generated plan to a
file on disk, which you can later execute by passing the file to
tofu apply as an extra argument. This two-step workflow
is primarily intended for when running OpenTofu in automation.
If you run tofu plan without the -out=FILE option then it will create
a speculative plan, which is a description of the effect of the plan but
without any intent to actually apply it.
In teams that use a version control and code review workflow for making changes to real infrastructure, developers can use speculative plans to verify the effect of their changes before submitting them for code review. However, it's important to consider that other changes made to the target system in the meantime might cause the final effect of a configuration change to be different than what an earlier speculative plan indicated, so you should always re-check the final non-speculative plan before applying to make sure that it still matches your intent.
Usage: tofu plan [options]
The plan subcommand looks in the current working directory for the root module
configuration.
Because the plan command is one of the main commands of OpenTofu, it has a variety of different options, described in the following sections. However, most of the time you should not need to set any of these options, because a OpenTofu configuration should typically be designed to work with no special additional options for routine work.
The remaining sections on this page describe the various options:
The previous section describes OpenTofu's default planning behavior, which
changes the remote system to match the changes you make to
your configuration. OpenTofu has two alternative planning modes, each of which creates a plan with a different intended outcome. These options are available for both tofu plan and tofu apply.
Destroy mode: creates a plan whose goal is to destroy all remote objects
that currently exist, leaving an empty OpenTofu state. It is the same as running tofu destroy. Destroy mode can be useful for situations like transient development environments, where the managed objects cease to be useful once the development task is complete.
Activate destroy mode using the -destroy command line option.
Refresh-only mode: creates a plan whose goal is only to update the OpenTofu state and any root module output values to match changes made to remote objects outside of OpenTofu. This can be useful if you've intentionally changed one or more remote objects outside of the usual workflow (e.g. while responding to an incident) and you now need to reconcile OpenTofu's records with those changes.
Activate refresh-only mode using the -refresh-only command line option.
In situations where we need to discuss the default planning mode that OpenTofu uses when none of the alternative modes are selected, we refer to it as "Normal mode". Because these alternative modes are for specialized situations only, some other OpenTofu documentation only discusses the normal planning mode.
The planning modes are all mutually-exclusive, so activating any non-default planning mode disables the "normal" planning mode, and you can't use more than one alternative mode at the same time.
In addition to alternate planning modes, there are several options that can modify planning behavior. These options are available for both tofu plan and tofu apply.
-refresh=false - Disables the default behavior of synchronizing the
OpenTofu state with remote objects before checking for configuration changes. This can make the planning operation faster by reducing the number of remote API requests. However, setting refresh=false causes OpenTofu to ignore external changes, which could result in an incomplete or incorrect plan. You cannot use refresh=false in refresh-only planning mode because it would effectively disable the entirety of the planning operation.
-replace=ADDRESS - Instructs OpenTofu to plan to replace the
resource instance with the given address. This is helpful when one or more remote objects have become degraded, and you can use replacement objects with the same configuration to align with immutable infrastructure patterns. OpenTofu will use a "replace" action if the specified resource would normally cause an "update" action or no action at all. Include this option multiple times to replace several objects at once. You cannot use -replace with the -destroy option.
-exclude=ADDRESS - Instructs OpenTofu to focus its planning efforts only
on resource instances which do not match the given excluded address, and that
do not depend on any such resources or modules that were excluded.
:::note
Use -exclude=ADDRESS in exceptional circumstances only, such as recovering from mistakes or working around OpenTofu limitations. Refer to Resource Targeting for more details.
:::
-exclude-file=FILENAME - Similar to -exclude but with multiple addresses
specified in a separate file rather than directly on the command line.
-target=ADDRESS - Instructs OpenTofu to focus its planning efforts only
on resource instances which match the given address and on any objects that
those instances depend on.
:::note
Use -target=ADDRESS in exceptional circumstances only, such as recovering from mistakes or working around OpenTofu limitations. Refer to Resource Targeting for more details.
:::
-target-file=FILENAME - Similar to -target but with multiple addresses
specified in a separate file rather than directly on the command line.
-var 'NAME=VALUE' - Sets a value for a single
input variable declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
Input Variables on the Command Line for more information.
-var-file=FILENAME - Sets values for potentially many
input variables declared in the
root module of the configuration, using definitions from a
"tfvars" file.
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the -var and -var-file options. Refer to
Assigning Values to Root Module Variables for more information.
You can use the -var command line option to specify values for
input variables declared in your
root module.
However, to do so will require writing a command line that is parsable both
by your chosen command line shell and OpenTofu, which can be complicated
for expressions involving lots of quotes and escape sequences. In most cases
we recommend using the -var-file option instead, and write your actual values
in a separate file so that OpenTofu can parse them directly, rather than
interpreting the result of your shell's parsing.
:::warning
OpenTofu will error if you include a space before or after the equals sign (e.g., -var "length = 2").
:::
To use -var on a Unix-style shell on a system like Linux or macOS we
recommend writing the option argument in single quotes ' to ensure the
shell will interpret the value literally:
tofu plan -var 'name=value'
If your intended value also includes a single quote then you'll still need to escape that for correct interpretation by your shell, which also requires temporarily ending the quoted sequence so that the backslash escape character will be significant:
tofu plan -var 'name=va'\''lue'
When using OpenTofu on Windows, we recommend using the Windows Command Prompt
(cmd.exe). When you pass a variable value to OpenTofu from the Windows
Command Prompt, use double quotes " around the argument:
tofu plan -var "name=value"
If your intended value includes literal double quotes then you'll need to escape those with a backslash:
tofu plan -var "name=va\"lue"
PowerShell on Windows cannot correctly pass literal quotes to external programs, so we do not recommend using OpenTofu with PowerShell when you are on Windows. Use Windows Command Prompt instead.
The appropriate syntax for writing the variable value is different depending
on the variable's type constraint.
The primitive types string, number, and bool all expect a direct string
value with no special punctuation except that required by your shell, as
shown in the above examples. For all other type constraints, including list,
map, and set types and the special any keyword, you must write a valid
OpenTofu language expression representing the value, and write any necessary
quoting or escape characters to ensure it will pass through your shell
literally to OpenTofu. For example, for a list(string) type constraint:
# Unix-style shell
tofu plan -var 'name=["a", "b", "c"]'
# Windows Command Prompt (do not use PowerShell on Windows)
tofu plan -var "name=[\"a\", \"b\", \"c\"]"
Similar constraints apply when setting input variables using environment variables. For more information on the various methods for setting root module input variables, see Assigning Values to Root Module Variables.
You can use the -target, -target-file, -exclude, and -exclude-file options
to activate resource targeting, which focuses OpenTofu's attention on only a
subset of the resource instances that are declared in the configuration or tracked
in the current state.
Using -target or -target-file focuses OpenTofu's attention only on resource
instances that match the given target addresses and resource instances that
are dependencies of those.
Using -exclude or -exclude-file instead focuses OpenTofu's attention on
resource instances other than those that match and anything that depends
on those.
Positive targeting using -target and -target-file is mutually exclusive with
negative targeting using -exclude and -exclude-file. You cannot use both
the target options and the exclude options together in a single command.
Specify the resource instances to target using resource address syntax.
For -target and -exclude, refer to
Resource Addresses on the Command Line.
For -target-file and -exclude-file, refer to
Resource Addresses in Targeting Files.
OpenTofu matches resource instances with the given resource addresses as follows:
If the given address identifies one specific resource instance, OpenTofu will select that instance alone.
For resources with either count or for_each set, a resource instance
address must include the instance index part, like aws_instance.example[0].
Your shell may assign special meaning to some punctuation characters used
in a resource instance address, such as quotes and brackets, so it's
important to properly quote or escape resource instance addresses written
directly on the command line in -target or -exclude options as
described in
Resource Addresses on the Command Line.
If the given address identifies a resource as a whole, OpenTofu will select
all of the instances of that resource. For resources with either count
or for_each set, this means selecting all instance indexes currently
associated with that resource. For single-instance resources (without
either count or for_each), the resource address and the resource instance
address are identical, so this possibility does not apply.
If the given address identifies an entire module instance, OpenTofu will select all instances of all resources that belong to that module instance and all of its child module instances.
This targeting capability is provided for exceptional circumstances, such as recovering from mistakes or working around OpenTofu limitations. It is not recommended to use these options for routine operations, because that can lead to undetected configuration drift and confusion about how the true state of resources relates to configuration.
Instead of using resource targeting to operate on isolated portions of very large configurations, prefer to break large configurations into several smaller configurations that can each be independently applied. You can use data sources to access information about resources declared in other configurations, allowing a complex system architecture to be broken down into more manageable parts that can be updated independently.
:::warning
Even though -target and -exclude both accept individual resource instance addresses,
due to some legacy decisions that cannot be undone without changing fully the way these features
work, using individual resource instance addresses for these should not be relied on.
Instead, these options should be used only with whole-resource addresses.
:::
The tofu plan command also has some other options that are related to
the input and output of the planning command, rather than customizing what
sort of plan OpenTofu will create. These commands are not necessarily also
available on tofu apply, unless otherwise stated in the documentation
for that command.
The available options are:
-compact-warnings - Shows any warning messages in a compact form which
includes only the summary messages, unless the warnings are accompanied by
at least one error and thus the warning text might be useful context for
the errors.
-consolidate-warnings=false - If OpenTofu produces any warnings, no
consolidation will be performed. All locations, for all warnings will
be listed. Enabled by default.
-consolidate-errors - If OpenTofu produces any errors, attempt to
consolidate similar messages into a single item.
-detailed-exitcode - Returns a detailed exit code when the command exits.
When provided, this argument changes the exit codes and their meanings to
provide more granular information about what the resulting plan contains:
-generate-config-out=PATH - (Experimental) If import blocks are present in configuration, instructs OpenTofu to generate HCL for any imported resources not already present. The configuration is written to a new file at PATH, which must not already exist, or OpenTofu will error. If the plan fails for another reason, OpenTofu may still attempt to write configuration.-input=false - Disables OpenTofu's default behavior of prompting for
input for root module input variables that have not otherwise been assigned
a value. This option is particularly useful when running OpenTofu in
non-interactive automation systems.
-json - Enables the machine readable JSON UI output.
This implies -input=false, so the configuration must have no unassigned
variable values to continue.
-lock=false - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same
workspace.
-lock-timeout=DURATION - Unless locking is disabled with -lock=false,
instructs OpenTofu to retry acquiring a lock for a period of time before
returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds.
-no-color - Disables terminal formatting sequences in the output. Use this
if you are running OpenTofu in a context where its output will be
rendered by a system that cannot interpret terminal formatting.
-concise - Disables progress-related messages in the output.
-out=FILENAME - Writes the generated plan to the given filename in an
opaque file format that you can later pass to tofu apply to execute
the planned changes, and to some other OpenTofu commands that can work with
saved plan files.
OpenTofu will allow any filename for the plan file, but a typical
convention is to name it tfplan. Do not name the file with a suffix
that OpenTofu recognizes as another file format; if you use a .tf or
.tofu suffix then OpenTofu will try to interpret the file as a
configuration source file, which will then cause syntax errors for subsequent
commands.
The generated file is not in any standard format intended for consumption by other software, but the file does contain your full configuration, all of the values associated with planned changes, and all of the plan options including the input variables. If your plan includes any sort of sensitive data, even if obscured in OpenTofu's terminal output, it will be saved in cleartext in the plan file. You should therefore treat any saved plan files as potentially-sensitive artifacts.
-parallelism=n - Limit the number of concurrent operations as OpenTofu
walks the graph. Defaults
to 10.
-state=statefile - A legacy option used for the local backend only.
Refer to the local backend's documentation for more information.
-show-sensitive - If specified, sensitive values will not be
redacted in te UI output.
-json - Produce output in a machine-readable JSON format, suitable for
use in text editor integrations and other automated systems.
-deprecation - Specify what type of warnings are shown.
Accepted values: "module:all", "module:local", "module:none". Default: "module:all". When "module:all" is selected,
OpenTofu will show the deprecation warnings for all modules. When "module:local" is selected,
the warnings will be shown only for the modules that are imported with a relative
path. When "module:none" is selected, all the deprecation warnings will be dropped.
For configurations using
the local backend only,
tofu plan accepts the legacy command line option
-state.
If your workflow relies on overriding the root module directory, use
the -chdir global option
instead, which works across all commands and makes OpenTofu consistently look
in the given directory for all files it would normally read or write in the
current working directory.