Getting started

This page covers the minimum steps to clone, build, test, and run Terraform from source. For the project's broader contribution guide, see .github/CONTRIBUTING.md.

Prerequisites

• Go. The exact toolchain version that produces the official binary is recorded in .go-version. As of writing, that file pins Go 1.25.x. Go 1.21+ will auto-download the version recorded in go.mod if your local toolchain is older.
• Git. Any reasonably recent version.
• Linux or macOS. The unit-test suite contains POSIX assumptions (path separators, max path lengths) and the project does not currently target Windows for development. The release binary itself works on Windows.
• (Optional) protoc if you intend to regenerate the Protocol Buffer stubs in docs/plugin-protocol/. See Makefile target protobuf.

Clone and build

git clone https://github.com/hashicorp/terraform.git
cd terraform
go install .

go install puts the resulting terraform binary in $(go env GOPATH)/bin. Make sure that directory is on your PATH. The first build downloads the dependencies recorded in go.sum (≈1100 modules); subsequent builds are much faster.

If you want a -dev suffix removed and experimental features enabled (matching how alpha builds are produced), use the ldflags documented in BUILDING.md:

go build -ldflags "-w -s \
  -X 'github.com/hashicorp/terraform/version.dev=no' \
  -X 'main.experimentsAllowed=yes'" -o bin/terraform .

Run the unit tests

The full unit-test suite is offline and self-contained:

go test ./...

Running everything takes a while (the suite is large; see by-the-numbers). To iterate on a single package:

go test ./internal/configs/...
go test ./internal/terraform -run TestContext2Plan

Tests live next to the code they cover, in *_test.go files. Many packages also use testdata/ directories with fixture configurations.

Acceptance tests

Tests that talk to external services (the Terraform Registry, HCP Terraform, real cloud providers used by the e2e tests) are gated behind the TF_ACC=1 environment variable:

TF_ACC=1 go test ./internal/initwd
TF_ACC=1 go test ./internal/getproviders

Acceptance tests are flaky by nature — services they depend on drift over time. Run them on main before you start a feature branch so you know which failures pre-date your work.

Code generation

Some files are generated. make generate (which calls go generate ./...) regenerates everything except the protobuf stubs:

make generate

To regenerate the gRPC stubs for the provider plugin protocol:

make protobuf

The protobuf step requires protoc and the Go protobuf plugins on PATH; the wrapper in tools/protobuf-compile/ documents the expected versions.

Lint and static analysis

The project uses three checks beyond go test:

make fmtcheck       # gofmt -d
make importscheck   # goimports
make vetcheck       # go vet ./...
make staticcheck    # honnef.co/go/tools/cmd/staticcheck (config in staticcheck.conf)
make exhaustive     # exhaustive enum-switch checker
make copyright      # HashiCorp copyright headers

Run all of them before opening a PR.

Run Terraform locally

Once you've installed the binary:

mkdir /tmp/tf-sandbox && cd /tmp/tf-sandbox
cat > main.tf <<'EOF'
terraform {
  required_providers {
    null = { source = "hashicorp/null" }
  }
}

resource "null_resource" "demo" {}
EOF

terraform init
terraform plan
terraform apply -auto-approve

State is written to terraform.tfstate in the current directory by default. Use -chdir to point at a different working directory without cd-ing:

terraform -chdir=/tmp/tf-sandbox plan

For end-to-end debugging of provider interactions, set TF_LOG=trace (see debugging).

Next steps

• Read architecture to learn how the pieces fit together.
• Browse systems to find the subsystem you want to change.
• Read the contribution guide before opening a PR.