opentofu/website/docs/cli/commands/state/rm.mdx

---
description: >-
  The `tofu state rm` command removes bindings from the OpenTofu state,
  causing OpenTofu to "forget about" existing objects.
---

# Command: state rm

The main function of [OpenTofu state](../../../language/state/index.mdx) is
to track the bindings between resource instance addresses in your configuration
and the remote objects they represent. Normally OpenTofu automatically
updates the state in response to actions taken when applying a plan, such as
removing a binding for a remote object that has now been deleted.

You can use `tofu state rm` in the less common situation where you wish
to remove a binding to an existing remote object without first destroying it,
which will effectively make OpenTofu "forget" the object while it continues
to exist in the remote system.

## Usage

Usage: `tofu state rm [options] ADDRESS...`

OpenTofu will search the state for any instances matching the given
[resource address](../../../cli/state/resource-addressing.mdx), and remove
the record of each one so that OpenTofu will no longer be tracking the
corresponding remote objects.

This means that although the objects will still continue to exist in the
remote system, a subsequent
[`tofu plan`](../../../cli/commands/plan.mdx)
will include an action to create a new object for each of the "forgotten"
instances. Depending on the constraints imposed by the remote system, creating
those objects might fail if their names or other identifiers conflict with
the old objects still present.

:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu state rm`.
:::

This command also accepts the following options:

- `-dry-run` - Report all of the resource instances that match the given
  address without actually "forgetting" any of them.

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

- `-var 'NAME=VALUE'` - Sets a value for a single
  [input variable](../../../language/values/variables.mdx) 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](../plan.mdx#input-variables-on-the-command-line) for more information.

- `-var-file=FILENAME` - Sets values for potentially many
  [input variables](../../../language/values/variables.mdx) declared in the
  root module of the configuration, using definitions from a
  ["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
  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](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.

For configurations using the [`cloud` backend](../../../cli/cloud/index.mdx) or the [`remote` backend](../../../language/settings/backends/remote.mdx)
only, `tofu state rm`
also accepts the option
[`-ignore-remote-version`](../../../cli/cloud/command-line-arguments.mdx#ignore-remote-version).

For configurations using
[the `local` state rm](../../../language/settings/backends/local.mdx) only,
`tofu state rm` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](../../../language/settings/backends/local.mdx#command-line-arguments).

## Example: Remove all Instances of a Resource

The following example will cause OpenTofu to "forget" all of the instances
of the `packet_device` resource named "worker".

```shell
$ tofu state rm 'packet_device.worker'
```

A resource that doesn't use `count` or `for_each` has only one instance, so
this is also the appropriate syntax to select that single instance.

## Example: Remove all Instances of a Resource in a Module

To select a resource that you've defined in a child module you must specify
the path of that module as part of the resource address:

```shell
$ tofu state rm 'module.foo.packet_device.worker'
```

## Example: Remove all Instances of all Resources in a Module

The following example will cause OpenTofu to "forget" all of the instances
associated with all resources defined in all instances of the module named
`foo`:

```shell
$ tofu state rm 'module.foo'
```

## Example: Remove a Particular Instance of a Resource using `count`

A resource defined with [the `count` meta-argument](../../../language/meta-arguments/count.mdx)
has multiple instances that are each identified by an integer. You can
select a particular instance by including an explicit index in your given
address:

```shell
$ tofu state rm 'packet_device.worker[0]'
```

Brackets (`[`, `]`) have a special meaning in some shells, so you may need to
quote or escape the address in order to pass it literally to OpenTofu.
The above shows the typical quoting syntax for Unix-style shells.

## Example: Remove a Particular Instance of a Resource using `for_each`

A resource defined with [the `for_each` meta-argument](../../../language/meta-arguments/for_each.mdx)
has multiple instances that are each identified by an string. You can
select a particular instance by including an explicit key in your given
address.

However, the syntax for strings includes quotes and the quote symbol often
has special meaning in command shells, so you'll need to use the appropriate
quoting and/or escaping syntax for the shell you are using. For example:

Unix-style shells, such as on Linux or macOS:

```shell
$ tofu state rm 'packet_device.worker["example"]'
```

Windows Command Prompt (`cmd.exe`):

```shell
$ tofu state rm packet_device.worker[\"example\"]
```

PowerShell:

```shell
$ tofu state rm 'packet_device.worker[\"example\"]'
```