Migrating existing Terraform configuration to OpenTofu

OpenTofu 1.6 is fully compatible with Terraform 1.6, making it easy to switch your existing infrastructure-as-code workflows. This guide walks you through a safe, step-by-step migration and provides tips for rollback and troubleshooting.

Prerequisites

Terraform 1.6.x installed
Access to your Terraform state file (terraform.tfstate)
A version-control backup or snapshot of your configuration

Step-by-Step Migration

Document a disaster recovery plan
Outline rollback procedures and how to restore state in case of unexpected issues.

Apply any pending Terraform changes

terraform init
terraform plan
terraform apply

Install OpenTofu
Follow the official installation guide for your OS: OpenTofu Installation.
Backup your Terraform state file
Note
Always version-control or copy your terraform.tfstate before you begin.
```
cp terraform.tfstate terraform.tfstate.backup
```
Initialize OpenTofu and preview the plan
```
tofu init
tofu plan
```
Test a non-critical change
Modify a minor resource to verify compatibility:
```
# Example: Update a tag on a test resource
tofu apply
```
Confirm that resources apply without drift before proceeding to production.

The image outlines a six-step process for migrating existing Terraform configurations to OpenTofu, including preparing a disaster recovery plan, applying changes, installing OpenTofu, backing up state files, initializing OpenTofu, inspecting the plan, and testing changes.

Getting Community Support

If you encounter issues during migration, leverage the OpenTofu community:

Join the OpenTofu Slack for real-time assistance.
Post in GitHub Discussions under “Q&A.”

The image is a diagram titled "Migrating Existing Terraform Configuration to OpenTofu," showing two options for support: OpenTofu Slack and GitHub Discussions.

If you need to revert to Terraform—whether due to workflow preference or compatibility issues—follow these steps:

Backup your OpenTofu state
Warning
Skipping this step may lead to state loss. Always keep a backup.
```
cp terraform.tfstate terraform.tfstate.backup
```
Re-initialize Terraform
```
terraform init
```
Review the execution plan
```
terraform plan
```
Apply a test change
```
terraform apply
```
Ensure the rollback completes successfully before normal operations.

The image outlines four steps for migrating back from OpenTofu to Terraform, including creating a backup, running terraform init, verifying the plan, and testing the rollback.

When you discover a bug in OpenTofu—during migration or rollback—please file a report on OpenTofu GitHub Issues. Include:

Report Type	Description
Bug report	Steps to reproduce, expected vs. actual behavior
Feature request (RFC)	Rationale, proposed API changes
Security vulnerability	Version details, impact analysis (use private channels)

Before You File

Search existing issues first and follow the issue templates.

The image illustrates a migration from OpenTofu to Terraform due to a bug, featuring icons of both platforms and a screenshot of the OpenTofu GitHub issues page.

Links and References

Watch Video

Watch video content