---
sidebar_position: 4
sidebar_label: Upgrading from earlier versions of OpenTofu
description: |-
    Learn how to upgrade OpenTofu to 1.12.
---

# Upgrading from earlier versions of OpenTofu

OpenTofu 1.12.x is largely compatible with previous OpenTofu versions. This migration guide will take you through the process of upgrading to OpenTofu v1.12.

## Step 0: Prepare a disaster recovery plan

Although OpenTofu v1.12 is mostly compatible with previous versions, you should take the necessary precautions to prevent accidents. Make sure you have an up-to-date and *tested* disaster recovery plan.

## Step 1: Apply all changes with your current OpenTofu version

Before proceeding, make sure that you apply all changes with `tofu apply`. Running `tofu plan` should result in no planned changes. While you can switch to OpenTofu with pending changes, it is not recommended.

```
$ tofu plan

...

No changes. Your infrastructure matches the configuration.

OpenTofu has compared your real infrastructure against your
configuration and found no differences, so no changes are needed.
```

## Step 2: Install OpenTofu v1.12

As a first step, [install the latest version from the v1.12.x series](intro/install/index.mdx).

Confirm that you are running the new version by running `tofu version`:

```
$ tofu version
OpenTofu v1.12.0
on linux_amd64
```

Your output should reflect whichever patch release you installed and the platform where you're running OpenTofu.

## Step 3: Back up your state file

Before you begin using the new OpenTofu version, take a backup of your latest state snapshot.

You can take a copy of the latest state snapshot by running `tofu state pull >backup.tfstate`, which will write the latest snapshot into `backup.tfstate` in your current working directory.
Alternatively, you can use a backup procedure tailored for the specific backend type you've chosen, such as making a copy of the state snapshot directly in the remote storage.

Make sure you know how to restore the backup you have created, just in case you encounter problems in the subsequent steps that prevent downgrading back to your previous version of OpenTofu.

## Step 4: Initialize OpenTofu 1.12.x

:::warning

If any of the following steps fail, we recommend that you stop following these instructions and refer to [Rolling back and reporting issues](#rolling-back-and-reporting-issues) below.

:::

Now you are ready to migrate. Run `tofu init` in the directory where your code resides. OpenTofu will download
any providers and modules referenced in your configuration from the OpenTofu registry.

## Step 5: Inspect the plan

Once initialized, run `tofu plan` and ensure that there are no pending changes similar to step 1 above. If there are
unexpected changes in the plan, roll back to your previous OpenTofu version and troubleshoot your migration.

```
$ tofu plan

...

No changes. Your infrastructure matches the configuration.

OpenTofu has compared your real infrastructure against your
configuration and found no differences, so no changes are needed.
```

## Step 6: Test out a small change

Before you begin using OpenTofu for larger changes, we recommend testing out `tofu apply` with a smaller, non-critical change.

## Rolling back and reporting issues

If you have issues migrating to OpenTofu you can follow these steps to roll back to your previous OpenTofu version:

1. Create another separate backup of your latest state snapshot, just in case one of the upgrade steps has changed it.
2. Remove OpenTofu 1.12.x and verify that you are running the same version of OpenTofu that was most recently working for you.
3. Run `tofu init`.
4. Run `tofu plan` and verify that no unexpected changes are in the plan.
5. Test the rollback with a small, non-critical change.

There are no intentional changes to the state snapshot format in this release and so it should not be necessary to restore the state snapshot backup you created earlier, but if you encounter any state-related errors when using your previous version then restoring the previous state snapshot is a good first troubleshooting step.

If you are rolling back because you've encountered a bug, please [report the bug to us on GitHub](https://github.com/opentofu/opentofu/issues).
