Migrating from Terraform

Move an existing project, safely.

Intermediate14 min · lesson 5 of 12

Migrating an existing Terraform project to OpenTofu is usually one of the smallest “migrations” you will ever do, precisely because the config and state are compatible. The core is: install tofu, run tofu init in the existing directory, and confirm a clean plan. The care goes into version alignment and the few HashiCorp-specific integrations that do not carry over.

terminal

$ cd existing-terraform-project
$ tofu init                 # reads the same .tf and the existing state
$ tofu plan
No changes. Your infrastructure matches the configuration.
# a clean "no changes" plan is the signal the migration is sound

What to check

Match the OpenTofu version to a Terraform version at or above your state’s (OpenTofu forked from 1.5, so 1.5-era state migrates cleanly; if you are on a newer Terraform using features OpenTofu had not yet added, check parity first). Back up your state before switching. And inventory the HashiCorp-specific pieces: Terraform Cloud/Enterprise remote runs, Sentinel policies, and some vendor CI actions need OpenTofu equivalents (a standard backend, OPA/Conftest for policy).

Migration in four steps

1back up state

copy it first

2install tofu

matched version

3tofu init

same dir + state

4plan = no changes

confirm parity

A “no changes” plan on first run is the whole acceptance test. Anything else, investigate before apply.

Back up state and go one directory at a time

Copy your state (or snapshot the remote backend) before the first tofu apply, and migrate one project/workspace at a time rather than the whole estate at once. If a plan shows unexpected changes, stop — it usually means a version-parity gap or a provider-source mismatch, not something to apply through.

State & the plan/apply workflowThe OpenTofu registry, providers…