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.

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​

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.