Terraform Module Source Types Explained: git / registry / local

The source argument on a module block is the single source of truth for where a module comes from. Get the syntax wrong and initialization, updates, and pinning all break down.

This article focuses on the three forms — registry / git / local — and zeroes in on real-world pitfalls and the points that show up most often on the Associate exam.

Module Source Basics and Resolution Flow

The source argument on a module block is the address Terraform uses to locate the module. The main forms are registry (public/private), git, and local (relative/absolute paths). terraform init resolves the source and fetches the module into .terraform/modules (local sources are referenced in place, not fetched).

The version argument — which lets you constrain a module's version — is only accepted by registry sources. With git you pin via ?ref= (tag, branch, or commit). With local you rely on repository management and release procedures. On the Associate exam, it's important to distinguish exactly which form lets you pin what.

• init resolves and fetches modules; always run it before plan/apply to refresh dependencies
• Only registry sources accept the version argument (SemVer constraints); git and local do not
• .terraform.lock.hcl primarily locks providers — module update control comes from the source spec and how you run init
• Common traps for git: //subdir and ?ref=. For local: relative paths are resolved from the working directory

Module source resolution flow (conceptual diagram)

Registry-Based Sources

Fetched from the public Terraform Registry or from a Terraform Cloud/Enterprise private registry. The syntax is <optional-hostname>/<namespace>/<module-name>/<provider>. If the hostname is omitted, it defaults to registry.terraform.io. For private registries, prefix the hostname (e.g. app.terraform.io).

The version argument accepts SemVer constraints (~>, >=, =, etc.). terraform init -upgrade updates to the latest version within the constraint, while init without -upgrade respects the existing cache. Authentication is typically handled by token management via terraform login.

• Public syntax example: source = "hashicorp/consul/aws"
• Private syntax example: source = "app.terraform.io/acme/network/aws"
• The version argument is registry-only (frequently tested)
• Combine init/upgrade behavior with version constraints to manage pinning in practice

Git-Based Sources

Fetched from a Git repository. Prefix the source with git:: and use either HTTPS or SSH. To target a subdirectory inside the repo, append //path/to/module. To pin the version, use ?ref=tag|branch|sha.

For authentication, prepare an HTTPS personal access token, or an SSH deploy key / SSH agent. In CI, the practical baseline is to inject credentials via environment variables or an auth agent — never hardcode them into the URL.

• HTTPS: source = "git::https://github.com/acme/infra-mods.git//modules/vpc?ref=v1.2.0"
• SSH: source = "git::ssh://[email protected]/acme/infra-mods.git//modules/vpc?ref=main"
• The version argument is not supported. Pin via ?ref= (tag/branch/commit) instead
• Without ref, you track the latest of the default branch, which destroys reproducibility (a classic exam trap)

Local Path Sources

Reference a module that exists in the same repository or on the local filesystem via a relative or absolute path. There is no fetch step — the module is referenced in place. Relative paths are resolved from the root module.

Changes are picked up immediately, but there is no version-pinning concept — reproducibility comes from branch workflows and release processes. Local sources don't scale to reuse across repositories; for that, promote to git or registry distribution.

• Relative path example: source = "./modules/network"
• Parent directory reference: source = "../shared/vpc"
• init does not build a cache, so module changes apply immediately (but always verify diffs with plan)
• For distribution and reuse, promote to git or registry-based modules

Comparing git / registry / local

Choose based on two criteria: reproducibility guarantees and ease of distribution. Registry is best for stable distribution across teams and organizations; git fits the development phase and internal sharing; local fits fast iteration inside a single repository.

• For maximum reproducibility: registry (version constraints + init workflow)
• As a middle ground: git (pin with ?ref=, mind authentication management)
• For local optimization and prototyping: local (promote to git/registry later)

Associate Exam Key Points and Samples

The three frequently tested pillars are: "version is registry-only", "for git, // means subdirectory and ?ref= means pinning", and "local sources are referenced directly without being fetched". Also nail down the meaning of init vs init -upgrade, the risk of omitting ref, and the hostname prefix for private registries.

Below are minimal examples of all three forms. Compare the syntax and pinning mechanism for each.

• registry: pin with version constraints and manage updates via upgrade
• git: combine //subdir with ?ref=. The version argument is not available
• local: path resolution is based on the root module's working directory

Minimal example of the three module source forms

module "net_registry" {
  source  = "app.terraform.io/acme/network/aws"
  version = "~> 1.2"
  cidr    = "10.0.0.0/16"
}

module "net_git" {
  source = "git::https://github.com/acme/infra-mods.git//modules/network?ref=v1.2.3"
  cidr   = "10.1.0.0/16"
}

module "net_local" {
  source = "./modules/network"
  cidr   = "10.2.0.0/16"
}

Check Your Understanding

Frequently Asked Questions