Skip to main content
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

  1. Document a disaster recovery plan
    Outline rollback procedures and how to restore state in case of unexpected issues.
  2. Apply any pending Terraform changes 
    terraform init
terraform plan
terraform apply
  3. Install OpenTofu
    Follow the official installation guide for your OS: OpenTofu Installation.
  4. Backup your Terraform state file
Always version-control or copy your terraform.tfstate before you begin.
cp terraform.tfstate terraform.tfstate.backup
  1. Initialize OpenTofu and preview the plan 
    tofu init
tofu plan
  2. 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:
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:
  1. Backup your OpenTofu state
Skipping this step may lead to state loss. Always keep a backup.
cp terraform.tfstate terraform.tfstate.backup
  1. Re-initialize Terraform 
    terraform init
  2. Review the execution plan 
    terraform plan
  3. 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 TypeDescription
Bug reportSteps to reproduce, expected vs. actual behavior
Feature request (RFC)Rationale, proposed API changes
Security vulnerabilityVersion details, impact analysis (use private channels)
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.

Watch Video