Terraform Registry: Public Distribution and Private Governance for Infrastructure as Code

The Terraform Registry is the default distribution and discovery layer for Terraform providers, modules, and policy libraries. It is integrated directly into the Terraform CLI so that a terraform init on a new project contacts registry.terraform.io, locates the providers declared in configuration, and downloads them without manual steps. Most engineers accept this as background infrastructure, but the registry is doing real work and understanding how it functions changes how you structure modules, manage providers, and govern IaC as a team scales.

The public registry gives 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 an organization control over what gets used and by whom. Knowing the difference, and when each applies, is foundational to running Terraform beyond a solo project.

What the Terraform Registry Contains and How It Works

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 the Terraform community. The goal 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 Registry is not a single thing. It is a comprehensive repository of all providers, modules, 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.

Providers are how Terraform integrates with any upstream API. The Terraform Registry is the main source for publicly available Terraform providers. It offers a browsable and searchable interface for finding providers, and makes it possible for Terraform CLI to automatically install any of the providers it hosts.

If you want Terraform to support a new infrastructure service, you can create your own provider using Terraform's Go SDK. Once you've developed a provider, you can use the Registry to share it with the rest of the community.

The registry has a number of different categories for modules, providers, and policies to help navigate 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.

Providers from the Registry

The Registry is directly integrated with Terraform. To use any provider from the Registry, all you need to do is require it within your Terraform configuration; Terraform can then automatically install that provider when initializing a working directory, and your configuration can take advantage of any resources implemented by that provider.

Terraform providers are published and maintained by a variety of sources, including HashiCorp, HashiCorp Technology Partners, and the Terraform community. The Registry uses tiers and badges to denote the source of a provider.

Using providers from the Registry removes the need to manually download binaries. When Terraform is installed for the first time on any system, the core responsible for running all the core commands is installed. However, this does not mean that any config created to provision infrastructure on any cloud provider platform will work without the provider plugin being fetched from the registry.

Public Registry Discovery and Publishing

Publish to the Terraform registry is the process for publishing Terraform providers, modules, and policies to the public Terraform registry. 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.

Individuals interested in publishing can use a GitHub account to sign in to the Terraform Registry. 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.

Module source references in the public registry follow the pattern registry.terraform.io/<namespace>/<name>/<system>. Example:

hcl module "azure_networking" { source = "registry.terraform.io/Azure/vnet/azurerm" version = "5.0.1" }

The public registry is integrated directly into Terraform so you can directly specify providers and modules. The registry is also browsable and searchable, supporting keyboard navigation for search.

Public vs Private Use Cases

Attribute	Public Terraform Registry	Private Terraform Registry
Audience	World-wide open source sharing	Organization-specific
Access control	Open	Only authorized users or teams can see or use modules and providers
Version management	Community managed versions	Publish multiple versions and control which ones are approved for production
Auditability	Limited to public data	Track who published which version and when
Consistency	Variable across community	Everyone uses the same vetted Terraform components, reducing drift and errors

Private Registry Architecture 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 a Private Registry Works

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.

A private registry centralizes modules so they can be versioned, reviewed, and reused across teams. The registry becomes the source of truth for approved building blocks.

Setting Up a Terraform Private Registry

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.

HCP Terraform Private Registry

Your organization on HCP Terraform comes with a private registry. You can use the private registry to publish modules for internal use, as well as publish custom providers.

To publish a module to the private registry on HCP Terraform, create a Git repository following the basic structure for a Terraform module:

. ├── README.md ├── main.tf # or possibly split into other .tf files ├── outputs.tf └── variables.tf

Next, go to the private registry of your HCP Terraform organization, select the publish module button, and follow the steps.

To use a published module from your HCP Terraform module registry, specify the hostname app.terraform.io together with the <namespace>/<name>/<system> string, following the naming convention for Terraform modules.

Here is an example of referencing a private AWS VPC module located in your HCP Terraform module registry:

hcl module "network" { source = "app.terraform.io/my-organization/vpc/aws" version = "1.0.0" cidr_block = "10.0.0.0/18" }

Provider Configuration with Private Registry

Providers can also be sourced from a private registry. Example provider block referencing a private registry:

hcl provider "aws" { alias = "primary" region = "us-east-1" }

When Terraform runs terraform init on a new project, something happens in the background: Terraform contacts registry.terraform.io, locates the providers you declared, and downloads them. With a private registry, the hostname is changed to your private registry host, ensuring only approved provider builds are pulled.

Third-Party and Self-Hosted Options

There are many third-party open-source alternatives to a Terraform private registry. Some options include Tapir, nrkno/terraform-registry, and terrareg. These options are outside the scope of a managed workflow but provide flexibility for teams that want full control.

Before selecting an open-source alternative, ensure the project is actively maintained.

Workflow Integration and Best Practices

A typical Terraform workflow is represented with 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.

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.

Practical considerations:

Use version pinning for modules and providers from the public registry to avoid unexpected breaking changes.
Mirror public modules to a private registry for supply-chain protection and air-gapped environments.
Establish a module review process before publishing to a private registry.
Document module inputs, outputs, and supported versions in README.md.
Use namespaces to separate teams or product lines inside a private registry.
Audit module usage across repositories to identify duplication and drift.

Terraform Registry Compatibility and Ecosystem Notes

The Terraform Registry is the official distribution platform for Terraform providers, modules, and policy libraries, hosted at registry.terraform.io, with broad module compatibility with the Terraform Registry. The public registry gives you access to thousands of provider plugins and reusable configuration templates. The private registry gives your organization control over what gets used and by whom.

In April 2026 the registry coverage was refreshed to cover Terraform 1.15 release candidate, OpenTofu registry differences, private registry options, and CI/CD automation patterns.

Conclusion

The Terraform Registry is both a public marketplace and a governance boundary. Publicly, it provides discoverable providers, modules, and policies with tiers and badges that denote source quality, and it is integrated so Terraform can automatically install any hosted provider. Privately, it becomes a control plane for standardization, access control, version management, auditability, and consistency across teams.

Organizations that treat the registry as background infrastructure risk supply-chain drift, uncontrolled module versions, and inconsistent builds. Organizations that treat the registry as a first-class artifact, with clear publishing pipelines, private hosting choices, and version policies, gain repeatable infrastructure delivery at scale.

Choosing between public consumption, self-hosted private registries, or managed options like HCP Terraform depends on compliance needs, team size, and risk tolerance. The registry you choose shapes how modules are discovered, vetted, and reused, and those decisions compound over time as infrastructure grows.