Terraform projects depend on a background step that most engineers treat as invisible infrastructure. When you run terraform init on a new project, Terraform contacts registry.terraform.io, locates the providers you declared, and downloads them. The registry is doing real work, and understanding how it functions changes how you structure modules, manage providers, and govern IaC as your team scales.
The public registry gives you access to thousands of provider plugins and reusable configuration templates. The private registry, whether hosted by HCP Terraform, env zero, GitLab, or a self-hosted solution, gives your organization control over what gets used and by whom. Knowing the difference, and when each applies, is foundational to running Terraform at anything beyond a solo project.
The decisions you make about the registry early, which modules to trust, how to version what you publish, whether to run your own private one, tend to compound. This covers the practical side of all three.
April 2026. Refreshed to cover Terraform 1.15 release candidate, OpenTofu registry differences, private registry options, and CI/CD automation patterns.
How Terraform Init Uses the Registry
Terraform is built using a modular approach. When Terraform is installed for the first time on any system, the core responsible for running all the core commands offered by Terraform is installed. However this does not mean that any config created to provision infrastructure on any cloud provider platform will work.
The Terraform Registry is the official distribution platform for Terraform providers, modules, and policy libraries. The Registry includes solutions developed by HashiCorp, third-party vendors, and our Terraform community. Our goal with the Registry is to provide plugins to manage any infrastructure API, pre-made modules to quickly configure common infrastructure components, and examples of how to write quality Terraform code.
The Terraform Registry is integrated directly into Terraform so you can directly specify providers and modules. Anyone can publish and consume providers, modules, and policies on the public Terraform Registry. To publish private modules within your organization, you can use a private registry or reference repositories and other sources directly.
Whenever we think of provisioning infrastructure using Terraform, we think of components like the configuration files, VCS, the Terraform host, the remote backend, etc. A typical Terraform workflow is represented in the diagram below. However we almost never mention the Terraform registry in this interpretation.
The existence of the Terraform registry is always assumed. Unlike the remote backends and VCS repositories, configuring the registry in our project, unless the registry is private, involves no manual steps, but the projects cannot run without the registry.
What the Terraform Registry contains
The registry isn't a single thing.
The Terraform Registry is an interactive resource for discovering a wide selection of integrations, configuration packages, and security rules for use with Terraform. The Registry has a number of different categories for modules, providers, and policies to help with navigating the large number of available options. Select a provider or module card to learn more, filter results to a specific tier, or use the search field at the top of the Registry. Search supports keyboard navigation.
Individuals interested in publishing can use a GitHub account to sign in to the Terraform Registry.
Public Registry Structure and Navigation
The landing page for the public Terraform registry is available at registry.terraform.io.
- To see the available providers you go to registry.terraform.io/browse/providers
- To see the available modules you go to registry.terraform.io/browse/modules
The page for each provider and module contain thorough documentation to help you get started using that provider or module.
Each module has its own dedicated git repository.
Terraform registry is a comprehensive repository of all providers, integrations, modules, configuration packages, policies, and run tasks designed to simplify Terraform workflows. HashiCorp maintains the registry with contributions from third-party vendors and the community, making building and scaling infrastructure easier.
Public vs Private Registry Characteristics
| Characteristic | Public Registry | Private Registry |
|---|---|---|
| Scope | Open to the whole world | Organization-specific |
| Access control | None, open read | Only authorized users or teams can see or use modules and providers |
| Version management | Community maintained versions | You can publish multiple versions and control which ones are approved for production |
| Auditability | Limited | You can track who published which version and when |
| Consistency | Variable community quality | Everyone uses the same vetted Terraform components, reducing drift and errors |
| Typical use | Open source sharing | Internal governance and supply chain risk reduction |
Referencing Providers and Modules from the Public Registry
Referencing a provider that is published to the public Terraform registry is done by specifying a URL in the format
As an example, for the AWS provider:
hcl
terraform {
required_providers {
aws = {
source = "registry.terraform.io/hashicorp/aws"
version = "5.58.0"
}
}
}
When you reference providers in the public Terraform registry you can skip the
The example above then becomes:
hcl
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "5.58.0"
}
}
}
No matter how you have referenced your providers they will be downloaded once you run terraform init:
$ terraform init
Initializing the backend...
Initializing provider plugins...
- Finding hashicorp/aws versions matching "5.58.0"...
- Installing hashicorp/aws v5.58.0...
- Installed hashicorp/aws v5.58.0 (signed by HashiCorp)
Terraform has created a lock file
Include this file in your version control repository so that Terraform can guarantee to make the same selections by default when you run "terraform init" in the future.
Terraform has been successfully initialized!
After running the terraform init command you can see the downloaded providers in your working directory, more specifically in a new directory named .terraform:
$ tree -a .
.
├── .terraform
│ └── providers
│ └── registry.terraform.io
│ └── hashicorp
│ └── aws
│ └── 5.58.0
│ └── linux_amd64
│ ├── LICENSE.txt
│ └── terraform-provider-aws_v5.58.0_x5
├── .terraform.lock.hcl
└── main.tf
7 directories, 4 files
The exact directory structure will depend on your computer architecture and what providers you are referencing.
Using modules from the public Terraform registry
Referencing a module from the public registry is similar to referencing providers, you use a URL in the format
hcl
module "network" {
source = "registry.terraform.io/terraform-aws-modules/vpc/aws"
version = "5.16.0"
}
Just like with providers you can use the shorthand reference:
hcl
module "network" {
source = "terraform-aws-modules/vpc/aws"
version = "5.16.0"
}
External modules from the public registry are downloaded and placed in the .terraform directory when you run terraform init:
$ terraform init
Initializing the backend...
Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/vpc/aws 5.16.0 for vpc...
- vpc in
The Terraform public registry is a great option when your goal is to share a module or provider with the whole world — for instance, when you write open-source modules and providers.
Private Registry Options and Governance
A Terraform private registry is a secure, organization-specific version of Terraform’s public registry. It serves as a central hub for sharing, versioning, and governing Terraform modules and providers within your company, rather than relying on the open, public Terraform Registry.
Private registries also provide:
- Access control: Only authorized users or teams can see or use the modules and providers.
- Version management: You can publish multiple versions and control which ones are approved for production.
- Auditability: You can track who published which version and when.
- Consistency: Everyone uses the same, vetted Terraform components, reducing drift and errors.
It lets teams standardize infrastructure building blocks, control access, and reduce supply-chain risk by curating what can be used and by whom.
You can run a registry yourself, use a managed option like HCP Terraform, or use a third-party registry such as Spacelift.
How does a Terraform private registry work
Most Terraform configurations that grow beyond a few resources and data sources should use Terraform modules. Terraform modules group logically connected pieces of infrastructure into a reusable package.
A module can be local, existing only as a subdirectory in the same Git repository as the root module where it is used. Using a local module means nobody else can reuse the same module without copying and pasting the same code into their own root module.
How to publish to Terraform private registries
There are three main options for how to set up a Terraform private registry:
- Build and host the private registry yourself.
- Use a managed private registry on your infrastructure automation platform, e.g., Spacelift or HCP Terraform.
- Use a third-party implementation of a private registry.
In the following sections, we discuss these options.
An example private module reference:
hcl
module "azure_networking" {
source = "registry.terraform.io/Azure/vnet/azurerm"
version = "5.0.1"
}
The private registry gives your organization control over what gets used and by whom. The public registry gives you access to thousands of provider plugins and reusable configuration templates.
Publishing and Consuming Workflows
Publish to the Terraform registry
Learn how to publish Terraform providers, modules, and policies to the public Terraform registry.
The Terraform Registry is an interactive resource for discovering a wide selection of integrations, configuration packages, and security rules for use with Terraform. The Registry includes solutions developed by HashiCorp, third-party vendors, and our Terraform community.
The registry has a number of different categories for modules, providers, and policies to help with navigating the large number of available options. Select a provider or module card to learn more, filter results to a specific tier, or use the search field at the top of the Registry. Search supports keyboard navigation.
Individuals interested in publishing can use a GitHub account to sign in to the Terraform Registry.
When you run terraform init on a new project, something happens in the background: Terraform contacts registry.terraform.io, locates the providers you declared, and downloads them. Most engineers accept this as background infrastructure and move on. But the registry is doing real work, and understanding how it functions changes how you structure modules, manage providers, and govern IaC as your team scales.
The private registry, whether hosted by HCP Terraform, env zero, GitLab, or a self-hosted solution, gives your organization control over what gets used and by whom. Knowing the difference, and when each applies, is foundational to running Terraform at anything beyond a solo project.
Conclusion
The Terraform Registry is not a single artifact but a layered system of distribution, discovery, and governance. The public registry at registry.terraform.io remains the default source for providers and modules, with direct integration into terraform init, shorthand source references, and lock file stability. It provides broad module compatibility with the Terraform Registry and a discoverable catalog of providers, modules, and policies contributed by HashiCorp, vendors, and the community.
Private registries shift the control plane inward. They provide access control, version management, auditability, and consistency for internal teams. Options range from self-hosted implementations to managed offerings on infrastructure automation platforms such as Spacelift or HCP Terraform, or third-party implementations.
The decisions you make about the registry early, which modules to trust, how to version what you publish, whether to run your own private one, tend to compound. Understanding the background work performed during terraform init, the URL formats for providers and modules, and the governance capabilities of private registries enables teams to standardize building blocks, reduce supply-chain risk, and maintain consistent infrastructure as usage scales.