How to Migrate From Terraform to OpenTofu

Fully open source until August 2023, Terraform is the most popular infrastructure-as-code (IaC) tool. After HashiCorp’s licensing changed to a more restrictive Business Source License, the community began looking elsewhere. This led to the OpenTofu initiative.

In this guide, you will learn why many teams are migrating to OpenTofu, the challenges they encounter, why the pre-migration checklist is important, and how to complete the migration step by step.

What we’ll cover:

1. Why migrate to OpenTofu?
2. What are the challenges when migrating from Terraform to OpenTofu?
3. Pre-migration checklist
4. Terraform to OpenTofu migration guide
5. How to roll back to Terraform

OpenTofu was created by leading companies in the infrastructure and DevOps space (Gruntwork, Spacelift, Harness, Env0, and Scalr) as a community response to Hashicorp’s decision to switch to BSL.

It was forked from Terraform version 1.5x and is open-source. It is operating under the Mozilla Public License v2.0 license and was accepted into the Cloud Native Computing Foundation (CNCF) in April 2025. This means that OpenTofu has institutional backing, no single vendor controls the project, and the decisions are made by a technical steering committee and the community.

The reasons to migrate to OpenTofu extend beyond licensing. For example, OpenTofu v1.7 offered state encryption, which the community had requested years ago from Terraform and which had been in their backlog since 2016. This feature helps teams stop worrying about sensitive data, such as database passwords, IDs, ARNs, tokens, IPs, etc., being stored in plaintext in state files.

As you probably know, you cannot use variables in the Terraform block (backend config, module source, etc.). OpenTofu changed that, introducing early variable evaluation into backend configurations and module sources in version v1.8.

Below you can find an example:

terraform {
 backend "s3" {
   bucket = var.bucket_name
 }
}

With this, you enable a dynamic backend and cleaner multi-environment configs.
Also, OpenTofu 1.9 introduced provider iteration with for_each, which became very useful for multi-region infrastructure and multi-account setups.

provider "aws" {
 for_each = var.regions
 region   = each.value
}

Migration from Terraform to OpenTofu is pretty simple; the challenges tend to be more operational and organizational.

Here are some of the challenges you might face when you are migrating from Terraform to OpenTofu:

• Operational scale and complexity: If you are using a single Terraform configuration, the migration to OpenTofu is easy. Things get complicated when you have hundreds or thousands of configurations across multiple environments. You will probably need some automation to run migrations across them, which should also validate if everything worked fine or not.
• HashiCorp registry references: You should check all hard-coded references to the HashiCorp registry. If you are using fully qualified provider names like registry.terraform.io/hashicorp/aws in your codebase, you will need to replace the prefix registry (e.g., registry.terraform.io), and you will end up with a result like hashicorp/aws. If you do not change the registry name, every tofu command you run will download and use the providers from HashiCorp’s registry.
• Provider and module compatibility: If you are using custom or niche providers, check whether they are available in the OpenTofu registry before starting the migration. You can actually contribute to the OpenTofu registry by copying these providers there.
• CI/CD pipeline updates: Another challenge when migrating to OpenTofu is updating your CI/CD pipelines (Jenkins, GitHub Actions, GitLab CI, etc.). If you are using terraform commands when running the pipelines, you need to replace them with the tofu ones.
• Version matching: Before migrating to OpenTofu, check your Terraform version. For example, if you are migrating from Terraform v1.5x or earlier, first migrate to OpenTofu v1.6x, then migrate to the latest version (or the version you want to use). You need to ensure that all your OpenTofu configurations are updated to reflect these changes.
• Keeping compatibility: If you want to keep compatibility between Terraform and OpenTofu (in some cases, you might still have teams that are not ready to migrate, and others that have already migrated, but they are using the same modules), you can use .tofu files.

For example, if you have a file called main.tf, and you want to use an OpenTofu-specific feature in it and also be able to run it from Terraform, you can create another file called main.tofu. In this case, Terraform will ignore the .tofu file, while OpenTofu will ignore the .tf file if there is a .tofu file with the same name.

Before migrating to OpenTofu, you need to check the following:

• Identify your Terraform version: Run the terraform version command to see which version you are using. After running this command, you need to decide which OpenTofu version you will need to migrate first.
• Apply all pending changes: Check whether any changes in your code have not been applied by running the terraform plan command. If there are some pending changes that need to be applied, apply them using terraform apply. The best practice is to have a clean, drift-free state file before migrating to OpenTofu.
• Back up your state file: If your state file is stored remotely (e.g., in an S3 bucket), ensure versioning is enabled. If this isn’t your case and you’re using local state (which you shouldn’t), make a copy of your terraform.tfstate file to a safe location.
• Back up and version your code: A best practice is to commit all your Terraform configurations to a version control system. In some situations, when migrations are done, they may require code changes.
• Audit your provider and module references: Check all your .tf files for references to registry.terraform.io and replace them with the corresponding OpenTofu references (e.g., AWS).
• Verify provider and module compatibility: All providers and modules you are using must be verified to ensure they are available in the OpenTofu registry.
• Checking your CI/CD pipelines: Identify whether you are running any terraform commands in your pipelines and replace them with the tofu ones after migration.
• Implement a disaster recovery strategy: You need to be prepared for anything unpredictable, so document your rollback steps (state restore procedures, code rollback steps). You can also test it before you migrate.
• Check for unsupported functions: Some Terraform functions may not be available in OpenTofu, so double-check how to replace them while preserving the functionality.

The pre-migration checklist is useful for preparing yourself for the migration process. Here are the actual steps that need to be followed for the migration to OpenTofu:

Step 1. Install OpenTofu

On macOS, to install OpenTofu, use the following command:

brew install opentofu

If you are a Linux user, there are two options: use the install script from the official docs or your package manager. After you have installed OpenTofu, verify:

tofu version

Learn more about how to install OpenTofu here.

Step 2. Initialize OpenTofu in your project

Go to the directory where your Terraform code is and run:

tofu init -upgrade

Use the flag -upgrade for OpenTofu to download providers and modules from the OpenTofu registry, rather than reusing the cached versions from the HashiCorp registry.

After running this command, you will see a success message that confirms initialization. If this step fails, follow your rollback procedure and troubleshoot the issue.

Step 3. Run a plan to check compatibility

Run a plan to check for changes in your code.

tofu plan

Investigate any unexpected changes before proceeding further.

Step 4. Run apply to update the state file

If there are no infrastructure changes, run:

tofu apply

Step 5. Verify your state integrity

You should run the following command to see that all your resources are tracked correctly:

tofu state list

Step 6. Test with a non-critical change

You should test your configuration with a small, low-risk change, such as adding a tag to your resource. Run tofu plan to verify the change was made, and then run tofu apply to execute it. If the change was applied correctly in your cloud console, OpenTofu can both read and write to your infrastructure.

Step 7. Update your CI/CD pipelines

You need to be sure that you replaced all your terraform commands in your pipelines with tofu ones. After you do that, you should run your pipelines in a non-production environment first to be sure everything is working as expected.

Step 8. Clean up

You should delete the .terraform directory, Terraform lock files, and any tools that are specific to Terraform. The only thing that you need to keep is .terraform.lock.hcl because OpenTofu is using it the same way as Terraform.

If you faced any problems during your migration process to OpenTofu, the rollback to Terraform is straightforward, especially if you made some backups: 

1. You may create a backup of your current state file and code, even though some parts are broken. You can use this backup later for debugging. 
2. Undo any changes that you made to your code during the migration process
3. If you are using a remote backend, restore the snapshot or versioned copy you created before the migration. 
4. Now you need to re-initialize Terraform by running the terraform init command.
5. Run a terraform plan to see if there are some changes. If the plan is clean, then you should run terrafom apply.
6. To be sure that Terrafom is working properly, test with a small change. 

If you have already started using OpenTofu and its features, like native state encryption or the .tofu file extension, the rollback process is more complex. You will need to decrypt your state file, then remove the OpenTofu-related syntax before reverting to Terraform. So, keeping pre-migration backups intact can be extremely helpful. 

Also, if you are having bugs during your migration to OpenTofu, you can always rely on the OpenTofu community. You can reach out to it via the OpenTofu Slack or file an issue on GitHub. 

Spacelift is an infrastructure orchestration platform that supports both OpenTofu and Terraform, as well as other tools such as Pulumi, CloudFormation, Terragrunt, Ansible, and Kubernetes. Spacelift offers a variety of features that map easily to your OpenTofu and Terraform workflow.

Spacelift stacks enable you to plug in the VCS repository containing your Terraform and OpenTofu configuration files and run a GitOps workflow for them.

At the stack level, you can add a variety of other components that will influence this GitOps workflow, such as:

• Policies control the kind of resources engineers can create, their parameters, the number of approvals you need for runs, where to send notifications, and more.
• Stack dependencies allow you to build dependencies between your configurations and even share outputs between them. There are no constraints on creating dependencies between multiple tools or the number of dependencies you can have.
• Cloud integrations are dynamic credentials for major cloud providers (AWS, Microsoft Azure, Google Cloud).
• Contexts are shareable containers for your environment variables, mounted files, and lifecycle hooks.
• Drift detection allows you to detect infrastructure drift easily and, optionally, remediate it.
• Resources view provides enhanced observability of all resources deployed with your Spacelift account.

For teams that want to move even faster on non-critical workloads, Spacelift Intent lets developers provision infrastructure using natural language, without writing any infrastructure as code, while the same policies, guardrails, and audit trails apply.

If you need help migrating from Terraform to OpenTofu or are looking for an infrastructure orchestration platform that supports the top flavors of infrastructure as code, configuration management, and container orchestration, contact Spacelift.

As a founding partner of the initiative, Spacelift offers the native and commercial support you need to ensure your OpenTofu success. Learn more about OpenTofu Commercial Support & Services.

Migrating from Terraform to OpenTofu is not difficult, as they share the same HCL language, the same provider ecosystem, very similar CLI commands, and the same state file format. If your team is using Terraform 1.5x or earlier, the migration will be practically a binary swap.

If you want a smooth migration, you should back up everything you can, match your Terraform version to the correct OpenTofu version, test in a non-production environment first, and also create a rollback plan.

OpenTofu is now a production-ready IaC tool adopted by many organizations and has progressed since 2023, when it was only an experimental tool. Migrating and managing your OpenTofu configuration is easier with Spacelift. To learn more about how we can help you with OpenTofu, book a demo with one of our engineers.