---
sidebar_position: 5
sidebar_label: Upgrading from OpenTofu 1.8.x/1.9.x/1.10.x
description: |-
    Learn how to upgrade OpenTofu from version 1.8.x/1.9.x/1.10.x to 1.11.0.
---

# Upgrading from OpenTofu 1.8.x/1.9.x/1.10.x

OpenTofu 1.11.x is mostly compatible with previous OpenTofu versions. This migration guide will take you through the process of upgrading OpenTofu to version 1.11.0.

## Step 0: Prepare a disaster recovery plan

Although OpenTofu 1.11 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 OpenTofu 1.7.x/1.8.x/1.9.x

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 1.11.x

As a first step, please [follow the installation instructions for the OpenTofu CLI tool](intro/install/index.mdx). Please test
if you can successfully execute the `tofu` command and receive the correct version:

```
$ tofu --version
OpenTofu v1.11.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 OpenTofu 1.11.x

:::warning

Should any of the following steps fail, please do not proceed and follow the
[rollback instructions below](#rolling-back-and-reporting-issues) instead.
If you suspect the failure may be the result of a bug in OpenTofu,
[please help us by opening an issue](https://github.com/opentofu/opentofu/issues).

:::

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.

:::note

If you are using the S3 backend - You will need to run `tofu init -reconfigure` to reinitialize the backend.

:::

## 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 OpenTofu 1.8.x/1.9.x/1.10.x and troubleshoot your migration. (See the Troubleshooting
section below.)

```
$ 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 OpenTofu 1.8.x/1.9.x/1.10.x:

1. Create another backup of your state file.
2. Remove OpenTofu 1.11.x and verify that you are running OpenTofu 1.8.x/1.9.x/1.10.x.
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](https://github.com/opentofu/opentofu/issues).

## Troubleshooting

If you encounter any issues during the migration to OpenTofu, you can join the <a href="/slack/">OpenTofu Slack</a> or ask on
[GitHub Discussions](https://github.com/orgs/opentofu/discussions).

### Error: Failed to query available provider packages

This error happens when a provider you specified in your configuration is not available in the OpenTofu registry.
Please roll back to OpenTofu 1.8.x/1.9.x/1.10.x and make sure your code works with that version. If your code works, please
[submit an issue to include the provider in the registry](https://github.com/opentofu/registry/issues/).

### Error: Module not found

This error happens when a module you specified in your configuration is not available in the OpenTofu registry.
Please roll back to OpenTofu 1.8.x/1.9.x/1.10.x and make sure your code works with that version. If your code works, please
[submit an issue to include the module in the registry](https://github.com/opentofu/registry/issues/).