OpenTofu Migration from Terraform: Production Guide 2026

OpenTofu: Terraform Migration Guide for Production

When HashiCorp changed Terraform’s license from MPL to BSL in 2023, the community forked it as OpenTofu — now a Linux Foundation project. For organizations evaluating the switch, this guide provides a practical comparison and step-by-step migration playbook for production environments.

OpenTofu vs Terraform: What Changed

OpenTofu 1.6+ is functionally equivalent to Terraform 1.6 with additions. Core HCL language, provider protocol, state format, and module system are identical. Key differences: OpenTofu remains MPL-2.0, has community governance, and adds features like client-side state encryption and an independent provider registry.

# OpenTofu-specific: client-side state encryption
terraform {
  encryption {
    key_provider "aws_kms" "main" {
      kms_key_id = "arn:aws:kms:us-east-1:123456789:key/xxx"
      region     = "us-east-1"
    }
    method "aes_gcm" "main" {
      keys = key_provider.aws_kms.main
    }
    state {
      method   = method.aes_gcm.main
      enforced = true
    }
  }
}

OpenTofu Migration: Production Checklist

# Step 1: Install OpenTofu
curl -sLO https://github.com/opentofu/opentofu/releases/download/v1.8.0/tofu_1.8.0_linux_amd64.zip
unzip tofu_1.8.0_linux_amd64.zip -d /usr/local/bin/

# Step 2: Verify compatibility
cd your-infrastructure/
tofu init            # Downloads from OpenTofu registry
tofu plan            # Should show ZERO changes

# Step 3: State file compatibility check
tofu state list      # Should match terraform state list
tofu state show aws_instance.web

# Step 4: Full plan comparison
terraform plan > tf-output.txt 2>&1
tofu plan > tofu-output.txt 2>&1
diff tf-output.txt tofu-output.txt  # Should be identical

# Step 5: Update CI/CD pipelines
# Step 6: Update lock file
tofu init -upgrade

CI/CD Pipeline Migration

# GitHub Actions: Before (Terraform)
- uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: 1.7.0
- run: terraform init && terraform plan

# GitHub Actions: After (OpenTofu)
- uses: opentofu/setup-opentofu@v1
  with:
    tofu_version: 1.8.0
- run: tofu init && tofu plan

# Atlantis migration
workflows:
  opentofu:
    plan:
      steps:
        - env:
            name: ATLANTIS_TF_BINARY
            value: /usr/local/bin/tofu
        - init
        - plan

Provider Registry and Backend Compatibility

OpenTofu runs its own registry at registry.opentofu.org with most providers mirrored automatically. State backends (S3, GCS, Azure Blob, PostgreSQL) are fully compatible — you can switch between Terraform and OpenTofu on the same state file without migration.

Should You Migrate?

Migrate if: you’re concerned about BSL licensing, you want community governance, or you want client-side state encryption. Stay with Terraform if: you rely on Terraform Cloud/Enterprise, have a HashiCorp enterprise agreement, or need single-vendor support. The migration is low-risk because state files are fully compatible — you can run both side-by-side and roll back instantly.

Key Takeaways

OpenTofu provides a genuinely open-source Terraform alternative with full compatibility. Migration is straightforward: install, verify with plan, update CI/CD, and switch. The risk is minimal because both tools read the same state files. For organizations valuing open-source governance, OpenTofu is the clear choice.