Upgrading from Earlier OpenTofu Release Series

We intend that it should typically be straightforward to upgrade from earlier versions of OpenTofu. This page describes the general process for moving to a newer minor release series.

Step 0: Prepare a disaster recovery plan​

Although new OpenTofu series are generally 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, we don't recommend it.

$ 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 the latest OpenTofu release​

First follow the installation instructions for OpenTofu CLI. Test that the tofu version command reports the expected version:

$ tofu version
OpenTofu v1.13.0
on linux_amd64

Step 3: Back up your state file​

Before you begin using the tofu binary on your Terraform code, make sure to back up your state file. If you are using a local state file, you can simply make a copy of your terraform.tfstate file in your project directory.

If you are using a remote backend such as an S3 bucket, make sure that you follow the backup procedures for the backend and that you exercise the restore procedure at least once.

Step 4: Initialize with the latest OpenTofu release​

Now you are ready to migrate. Run tofu init in the directory where your code resides. OpenTofu will download any providers and modules used by your configuration from 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 the version you were previously using 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, test 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 the version you were previously using:

1. Create another backup of your state file.
2. Remove the newly-installed OpenTofu version and verify that you are now running whatever version you were previously using.
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.

If you encountered a bug, please report it on GitHub.