Go Installation and Setup

7 minute read

Go Installation and Setup

Go (Golang) is the programming language for building Terraform providers. In this chapter, you’ll install Go 1.21 or later and configure your development environment.

The Terraform Plugin Framework requires Go 1.21+ for its latest features, including improved generics support and enhanced error handling.

Why Go 1.21+?

Key Features for Provider Development

  • Improved Generics — Better type safety in framework code
  • Enhanced Error Handling — Cleaner error wrapping
  • Performance Improvements — Faster compilation and runtime
  • Standard Library Updates — New packages for common tasks
  • Security Fixes — Latest security patches

Version Requirements

Component Minimum Go Version
Terraform Plugin Framework Go 1.21+
Terraform Plugin Testing Go 1.21+
This Tutorial Go 1.21+

Recommended: Go 1.22 or 1.23 (latest stable)

Pre-Installation Check

Before installing, check if Go is already installed:

go version

Expected output (if installed):

go version go1.22.4 darwin/arm64

If you see a version 1.21 or higher, you’re ready to go! Skip to Verify Installation.

If you see an older version or command not found, continue with installation.

Installation by Platform

Choose your operating system:

macOS Installation

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Go
brew install go

# Verify installation
go version

Option 2: Using Official Installer

  1. Download from https://go.dev/dl/
  2. Choose: go1.XX.X.darwin-amd64.pkg (Intel) or go1.XX.X.darwin-arm64.pkg (Apple Silicon)
  3. Double-click the .pkg file
  4. Follow installation wizard
  5. Restart Terminal

Option 3: Using asdf (Version Manager)

# Install asdf
brew install asdf

# Add Go plugin
asdf plugin add golang

# Install latest Go
asdf install golang latest

# Set as global version
asdf global golang latest

# Verify
go version

Linux Installation

Option 1: Using Package Manager

Ubuntu/Debian:

# Add Go PPA for latest version
sudo add-apt-repository ppa:longsleep/golang-backports
sudo apt update

# Install Go
sudo apt install golang-go

# Verify
go version

Fedora/RHEL/CentOS:

# Install Go
sudo dnf install golang

# Verify
go version

Arch Linux:

# Install Go
sudo pacman -S go

# Verify
go version

Option 2: Manual Installation (All Distributions)

# Download latest Go (replace X.XX.X with latest version)
wget https://go.dev/dl/go1.22.4.linux-amd64.tar.gz

# Remove old Go installation (if exists)
sudo rm -rf /usr/local/go

# Extract to /usr/local
sudo tar -C /usr/local -xzf go1.22.4.linux-amd64.tar.gz

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Verify
go version

Windows Installation

  1. Download from https://go.dev/dl/
  2. Choose: go1.XX.X.windows-amd64.msi
  3. Run the installer
  4. Follow installation wizard
  5. Restart Command Prompt or PowerShell

Option 2: Using Chocolatey

# Install Chocolatey if not installed
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install Go
choco install golang

# Verify
go version

Option 3: Using WSL2 (Windows Subsystem for Linux)

# From WSL2 terminal, follow Linux instructions
sudo add-apt-repository ppa:longsleep/golang-backports
sudo apt update
sudo apt install golang-go
go version

Environment Configuration

After installation, configure your Go environment.

Understanding GOPATH

GOPATH is where Go stores downloaded packages and compiled binaries.

# Check current GOPATH
go env GOPATH

Default locations:

  • macOS/Linux: ~/go
  • Windows: %USERPROFILE%\go

Set Up Go Environment

Add these to your shell configuration file:

For macOS/Linux (.bashrc, .zshrc, .bash_profile):

# Go configuration
export GOPATH=$HOME/go
export GOBIN=$GOPATH/bin
export PATH=$PATH:/usr/local/go/bin:$GOBIN

# Optional: Enable Go modules (default in Go 1.16+)
export GO111MODULE=on

# Optional: Set Go proxy for faster downloads
export GOPROXY=https://proxy.golang.org,direct

For Windows (PowerShell Profile):

# Edit profile
notepad $PROFILE

# Add these lines:
$env:GOPATH = "$env:USERPROFILE\go"
$env:GOBIN = "$env:GOPATH\bin"
$env:PATH += ";C:\Go\bin;$env:GOBIN"

Apply changes:

# macOS/Linux
source ~/.bashrc  # or ~/.zshrc

# Windows
. $PROFILE

Create Go Workspace

# Create Go workspace directories
mkdir -p $GOPATH/{src,bin,pkg}

# Create directory for your providers
mkdir -p $GOPATH/src/github.com/yourusername

Verify Installation

Run these commands to verify your Go setup:

1. Check Go Version

go version

Expected output:

go version go1.22.4 darwin/arm64

Ensure version is 1.21 or higher.

2. Check Go Environment

go env

Key variables to verify:

GOPATH="/Users/username/go"
GOROOT="/usr/local/go"
GOBIN="/Users/username/go/bin"
GOOS="darwin"  # or "linux" or "windows"
GOARCH="amd64"  # or "arm64"

3. Test Go Installation

Create a simple test program:

# Create test directory
mkdir -p ~/go-test && cd ~/go-test

# Initialize Go module
go mod init example.com/hello

# Create main.go
cat > main.go << 'EOF'
package main

import "fmt"

func main() {
    fmt.Println("Go is installed correctly!")
    fmt.Println("Ready for Terraform provider development!")
}
EOF

# Run the program
go run main.go

Expected output:

Go is installed correctly!
Ready for Terraform provider development!

4. Test Module Download

# Test dependency download
go get github.com/hashicorp/terraform-plugin-framework/provider

# Verify it downloaded
go list -m github.com/hashicorp/terraform-plugin-framework

Expected output:

github.com/hashicorp/terraform-plugin-framework v1.5.0

If all tests pass, your Go installation is working correctly!

Install Additional Tools

Install essential Go development tools:

1. gopls (Go Language Server)

go install golang.org/x/tools/gopls@latest

Provides IDE features like autocomplete and refactoring.

2. golangci-lint (Linter)

# macOS/Linux
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

# Verify
golangci-lint --version

3. goimports (Import Formatter)

go install golang.org/x/tools/cmd/goimports@latest

4. dlv (Delve Debugger)

go install github.com/go-delve/delve/cmd/dlv@latest

Verify Tools Installation

# Check all tools are in PATH
which gopls goimports dlv golangci-lint

Go Workspace Structure

Your Go workspace should look like this:

$GOPATH/
├── bin/           # Compiled binaries and tools
│   ├── gopls
│   ├── golangci-lint
│   └── terraform-provider-mycloud
├── pkg/           # Compiled package objects (cached)
│   └── mod/       # Downloaded module cache
└── src/           # Source code (optional, legacy)
    └── github.com/
        └── yourusername/
            └── terraform-provider-mycloud/

Note: With Go modules (default since Go 1.16), you can work anywhere, not just in $GOPATH/src.

Go Modules Primer

Modern Go uses modules for dependency management.

Key Commands

# Initialize a new module
go mod init github.com/username/project

# Add dependencies
go get github.com/package/name

# Update dependencies
go get -u ./...

# Remove unused dependencies
go mod tidy

# Vendor dependencies (optional)
go mod vendor

# List dependencies
go list -m all

# Check why a dependency is needed
go mod why github.com/package/name

go.mod Example

module github.com/username/terraform-provider-mycloud

go 1.22

require (
    github.com/hashicorp/terraform-plugin-framework v1.5.0
    github.com/hashicorp/terraform-plugin-go v0.21.0
    github.com/hashicorp/terraform-plugin-log v0.9.0
)

Common Installation Issues

Issue: “go: command not found”

Solution:

# Check if Go is in PATH
echo $PATH | grep go

# Add Go to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=$PATH:/usr/local/go/bin:$GOPATH/bin
source ~/.bashrc

Issue: Permission Denied

Solution:

# Fix GOPATH permissions
sudo chown -R $USER:$USER $GOPATH

# Or use sudo for installation
sudo go install package@latest

Issue: SSL Certificate Errors

Solution:

# Bypass SSL verification (temporary)
git config --global http.sslVerify false

# Or set proxy
export GOPROXY=https://proxy.golang.org,direct

Issue: Old Go Version

Solution:

# Uninstall old version
sudo rm -rf /usr/local/go

# Install new version (see installation instructions above)

Issue: Module Download Fails

Solution:

# Clear module cache
go clean -modcache

# Set proxy
go env -w GOPROXY=https://proxy.golang.org,direct

# Retry download
go mod download

IDE Configuration

VS Code Setup

  1. Install VS Code: https://code.visualstudio.com/

  2. Install Go Extension:
    • Open VS Code
    • Press Cmd+Shift+X (macOS) or Ctrl+Shift+X (Windows/Linux)
    • Search for “Go”
    • Install “Go” by Go Team at Google
  3. Install Go Tools:
    • Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
    • Type “Go: Install/Update Tools”
    • Select all tools
    • Click “OK”
  4. Configure Settings (settings.json):
{
  "go.useLanguageServer": true,
  "go.lintTool": "golangci-lint",
  "go.lintOnSave": "package",
  "go.formatTool": "goimports",
  "go.formatOnSave": true,
  "go.testFlags": ["-v"],
  "[go]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  }
}

GoLand Setup

  1. Install GoLand: https://www.jetbrains.com/go/

  2. Configure Go SDK:
    • Preferences → Go → GOROOT
    • Select your Go installation (/usr/local/go)
  3. Enable Go Modules:
    • Preferences → Go → Go Modules
    • Check “Enable Go modules integration”
  4. Configure Code Style:
    • Preferences → Editor → Code Style → Go
    • Use “gofmt” style

Best Practices

1. Keep Go Updated

# Check for updates regularly
go version

# Update via package manager
brew upgrade go  # macOS
sudo apt upgrade golang-go  # Ubuntu

2. Use Go Modules

Always use modules for dependency management:

# Start every project with
go mod init github.com/username/project

3. Run gofmt Regularly

# Format all Go files
gofmt -w .

# Or use goimports (better)
goimports -w .

4. Use golangci-lint

# Lint your code
golangci-lint run

5. Vendor Dependencies (Optional)

For reproducible builds:

go mod vendor

Quick Reference

Essential Commands

# Run Go program
go run main.go

# Build executable
go build

# Install to $GOBIN
go install

# Run tests
go test ./...

# Download dependencies
go mod download

# Clean module cache
go clean -modcache

# Format code
gofmt -w .

# Lint code
golangci-lint run

Key Takeaways

  • ✅ Go 1.21+ is required for provider development
  • ✅ Install via package manager or official installer
  • ✅ Configure GOPATH and PATH environment variables
  • ✅ Verify installation with go version and test programs
  • ✅ Install development tools (gopls, golangci-lint, goimports)
  • ✅ Use Go modules for all projects
  • ✅ Configure your IDE for Go development

What’s Next?

Now that Go is installed and configured, let’s scaffold your first provider project!

Next: Project Scaffolding →

Further Reading

Previous: ← Development Setup Overview

Last updated: June 30, 2026

Updated:

You may also enjoy