---
description: >-
  The source argument tells OpenTofu where to find child modules's
  configurations in locations like GitHub, the OpenTofu Registry, Bitbucket,
  Git, Mercurial, S3, and GCS.
---

# Module Sources

The `source` argument in [a `module` block](../../language/modules/syntax.mdx)
tells OpenTofu where to find the source code for the desired child module.

OpenTofu uses this during the module installation step of `tofu init`
to download the source code to a directory on local disk so that other OpenTofu commands can use it.

The module installer supports installation from a number of different source
types.

- [Local paths](#local-paths)

- [Module Registry](#module-registry)

- [GitHub](#github)

- [Bitbucket](#bitbucket)

- Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories

- [OCI Distribution](#oci-distribution-repository) repositories

- [HTTP URLs](#http-urls)

- [S3 buckets](#s3-bucket)

- [GCS buckets](#gcs-bucket)

- [Modules in Package Sub-directories](#modules-in-package-sub-directories)

Each of these is described in the following sections. Module source addresses
use a _URL-like_ syntax, but with extensions to support unambiguous selection
of sources and additional features.

We recommend using local file paths for closely-related modules used primarily
for the purpose of factoring out repeated code elements, and using a native
OpenTofu module registry for modules intended to be shared by multiple calling
configurations. We support other sources so that you can potentially distribute
OpenTofu modules internally with existing infrastructure.

Many of the source types will make use of "ambient" credentials available
when OpenTofu is run, such as from environment variables or credentials files
in your home directory. This is covered in more detail in each of the following
sections.

We recommend placing each module that is intended to be re-usable in the root
of its own repository or archive file, but it is also possible to
[reference modules from subdirectories](#modules-in-package-sub-directories).

## Local Paths

Local path references allow for factoring out portions of a configuration
within a single source repository.

```hcl
module "consul" {
  source = "./consul"
}
```

A local path must begin with either `./` or `../` to indicate that a local
path is intended, to distinguish from
[a module registry address](#module-registry).

Local paths are special in that they are not "installed" in the same sense
that other sources are: the files are already present on local disk (possibly
as a result of installing a parent module) and so can just be used directly.
Their source code is automatically updated if the parent module is upgraded.

Note that OpenTofu does not consider an _absolute_ filesystem path (starting
with a slash, a drive letter, or similar) to be a local path. Instead,
OpenTofu will treat that in a similar way as a remote module and copy it into
the local module cache. An absolute path is a "package" in the sense described
in [Modules in Package Sub-directories](#modules-in-package-sub-directories).
We don't recommend using absolute filesystem paths to refer to modules,
because it will tend to couple your configuration to the filesystem
layout of a particular computer.

## Module Registry

A module registry is the native way of distributing modules for use
across multiple configurations, using an OpenTofu-specific protocol that
has full support for module versioning.

The [Public OpenTofu Registry](https://registry.opentofu.org/) is an index of modules
shared publicly using this protocol. This public registry is the easiest way
to get started with OpenTofu and find modules created by others in the
community.

You can also use a
[private registry](../../internals/module-registry-protocol.mdx), either
via [TACOS](../../intro/tacos.mdx) (TF Automation and Collaboration Software), or by running a custom
service that implements
[the module registry protocol](../../internals/module-registry-protocol.mdx).

Modules on the public registry can be referenced using a registry
source address of the form `<NAMESPACE>/<NAME>/<PROVIDER>`, with each
module's information page on the registry site including the exact address
to use.

```hcl
module "consul" {
  source = "hashicorp/consul/aws"
  version = "0.1.0"
}
```

The above example will use the
[Consul module for AWS](https://github.com/hashicorp/terraform-aws-consul)
from a public registry.

For modules hosted in other registries, prefix the source address with an
additional `<HOSTNAME>/` portion, giving the hostname of the private registry:

```hcl
module "consul" {
  source = "app.terraform.io/example-corp/k8s-cluster/azurerm"
  version = "1.1.0"
}
```

Registry modules support versioning. You can provide a specific version as shown
in the above examples, or use flexible
[version constraints](../../language/modules/syntax.mdx#version).

You can learn more about the registry at the
[Module Registry documentation](../../internals/module-registry-protocol.mdx).

To access modules from a private registry, you may need to configure an access
token [in the CLI config](../../cli/config/config-file.mdx#credentials). Use the
same hostname as used in the module source string. For a private registry
within [TACOS](../../intro/tacos.mdx) (TF Automation and Collaboration Software), use the same authentication token as you would
use with the API or command-line clients.

## GitHub

OpenTofu will recognize unprefixed `github.com` URLs and interpret them
automatically as Git repository sources.

```hcl
module "consul" {
  source = "github.com/hashicorp/example"
}
```

The above address scheme will clone over HTTPS. To clone over SSH, use the
following form:

```hcl
module "consul" {
  source = "git@github.com:hashicorp/example.git"
}
```

These GitHub schemes are treated as convenient aliases for
[the general Git repository address scheme](#generic-git-repository), and so
they obtain credentials in the same way and support the `ref` argument for
selecting a specific revision. You will need to configure credentials in
particular to access private repositories.

## Bitbucket

OpenTofu will recognize unprefixed `bitbucket.org` URLs and interpret them
automatically as BitBucket repositories:

```hcl
module "consul" {
  source = "bitbucket.org/example-corp/tofu-consul-aws"
}
```

This shorthand works only for public repositories, because OpenTofu must
access the BitBucket API to learn if the given repository uses Git or Mercurial.

OpenTofu treats the result either as [a Git source](#generic-git-repository)
or [a Mercurial source](#generic-mercurial-repository) depending on the
repository type. See the sections on each version control type for information
on how to configure credentials for private repositories and how to specify
a specific revision to install.

## Generic Git Repository

Arbitrary Git repositories can be used by prefixing the address with the
special `git::` prefix. After this prefix, any valid
[Git URL](https://git-scm.com/docs/git-clone#_git_urls)
can be specified to select one of the protocols supported by Git.

For example, to use HTTPS or SSH:

```hcl
module "vpc" {
  source = "git::https://example.com/vpc.git"
}

module "storage" {
  source = "git::ssh://username@example.com/storage.git"
}
```

OpenTofu installs modules from Git repositories by running `git clone`, and
so it will respect any local Git configuration set on your system, including
credentials. To access a non-public Git repository, configure Git with
suitable credentials for that repository.

If you use the SSH protocol then any configured SSH keys will be used
automatically. This is the most common way to access non-public Git
repositories from automated systems because it allows access to private
repositories without interactive prompts.

If using the HTTP/HTTPS protocol, or any other protocol that uses
username/password credentials, configure
[Git Credentials Storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage)
to select a suitable source of credentials for your environment.

### Selecting a Revision

By default, OpenTofu will clone and use the default branch (referenced by
`HEAD`) in the selected repository. You can override this using the
`ref` argument. The value of the `ref` argument can be any reference that would be accepted
by the `git checkout` command, such as branch, SHA-1 hash (short or full), or tag names.
For a full list of the possible values, see
[Git Tools - Revision Selection](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#_single_revisions)
in [the Git Book](https://git-scm.com/book/en/v2).

```hcl
# select a specific tag
module "vpc" {
  source = "git::https://example.com/vpc.git?ref=v1.2.0"
}

# directly select a commit using its SHA-1 hash
module "storage" {
  source = "git::https://example.com/storage.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"
}
```

### Shallow Clone

For larger repositories you may prefer to make only a shallow clone in order
to reduce the time taken to retrieve the remote repository.

The `depth` URL argument corresponds to
[the `--depth` argument to `git clone`](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt),
telling Git to create a shallow clone with the history truncated to only
the specified number of commits.

However, because shallow clone requires different Git protocol behavior,
setting the `depth` argument makes OpenTofu pass your [`ref` argument](#selecting-a-revision),
if any, to
[the `--branch` argument to `git clone`](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---branchltnamegt)
instead. That means it must specify a named branch or tag known to the remote
repository, and that raw commit IDs are not acceptable.

Because OpenTofu only uses the most recent selected commit to find the source
code of your specified module, it is not typically useful to set `depth`
to any value other than `1`.

### "scp-like" address syntax

When using Git over SSH, we recommend using the `ssh://`-prefixed URL form
for consistency with all of the other URL-like git address forms.
You may opt to use the alternative "scp-like" syntax instead, in which case you
must omit the `ssh://` scheme part and include only the `git::` part.
For example:

```hcl
module "storage" {
  source = "git::username@example.com:storage.git"
}
```

If you use the `ssh://` URL scheme then OpenTofu will assume that the colon
marks the beginning of a port number, rather than the beginning of the path.
This matches how Git itself interprets these different forms, aside from
the OpenTofu-specific `git::` selector prefix.

## Generic Mercurial Repository

You can use arbitrary Mercurial repositories by prefixing the address with the
special `hg::` prefix. After this prefix, any valid
[Mercurial URL](https://www.mercurial-scm.org/repo/hg/help/urls)
can be specified to select one of the protocols supported by Mercurial.

```hcl
module "vpc" {
  source = "hg::http://example.com/vpc.hg"
}
```

OpenTofu installs modules from Mercurial repositories by running `hg clone`, and
so it will respect any local Mercurial configuration set on your system,
including credentials. To access a non-public repository, configure Mercurial
with suitable credentials for that repository.

If you use the SSH protocol then any configured SSH keys will be used
automatically. This is the most common way to access non-public Mercurial
repositories from automated systems because it allows access to private
repositories without interactive prompts.

### Selecting a Revision

You can select a non-default branch or tag using the optional `ref` argument:

```hcl
module "vpc" {
  source = "hg::http://example.com/vpc.hg?ref=v1.2.0"
}
```

## OCI Distribution Repository

The OCI Distribution protocol is a generalization of the protocol originally
used by Docker for distributing container images. OpenTofu can install
module packages from specially-formatted artifacts published into repositories
in OCI Registries.

```hcl
module "example" {
  source = "oci://example.com/repository-name"
}
```

The domain name specified immediately after the `oci://` prefix is the OCI
Registry domain name. The remainder of the address specifies a specific
repository name within that repository.

If your specified OCI Registry requires authentication credentials,
refer to [OCI Registry Credentials](/cli/oci_registries/credentials.mdx).

### Selecting a Tag or Digest

By default, OpenTofu attempts to retrieve the artifact associated with the
remote tag named "latest". You can select a different artifact using
one of the following arguments in the query string:

- `tag` specifies a different tag name to use.
- `digest` directly specifies the digest of the manifest of the desired
  artifact, totally ignoring the tags defined in the repository.

Only one of these arguments at a time can be used in a valid source address.

For example, to select a tag named `v1.0.0`:

```hcl
module "example" {
  source = "oci://example.com/repository-name?tag=v1.0.0"
}
```

### Building a module package artifact

For more information on the manifest structure that OpenTofu expects for
module package artifacts, refer to
[Module Packages in OCI Registries](/cli/oci_registries/module-package.mdx).

## HTTP URLs

When you use an HTTP or HTTPS URL, OpenTofu will make a `GET` request to
the given URL, which can return _another_ source address. This indirection
allows using HTTP URLs as a sort of "vanity redirect" over a more complicated
module source address.

OpenTofu will append an additional query string argument `tofu-get=1` to
the given URL before sending the `GET` request, allowing the server to
optionally return a different result when OpenTofu is requesting it.

If the response is successful (`200`-range status code), OpenTofu looks in
the following locations in order for the next address to access:

- The value of a response header field named `X-Terraform-Get`.

- If the response is an HTML page, a `meta` element with the name `tofu-get`:

  ```html
  <meta name="tofu-get" content="github.com/hashicorp/example" />
  ```

In either case, the result is interpreted as another module source address
using one of the forms documented elsewhere on this page.

If an HTTP/HTTPS URL requires authentication credentials, use a `.netrc`
file to configure the credentials. By default, OpenTofu searches for the `.netrc` file
in your HOME directory. However, you can override the default filesystem location by setting the `NETRC` environment variable. For information on the `.netrc` format,
refer to [the documentation for using it in `curl`](https://everything.curl.dev/usingcurl/netrc).

### Fetching archives over HTTP

As a special case, if OpenTofu detects that the URL has a common file
extension associated with an archive file format then it will bypass the
special `tofu-get=1` redirection described above and instead just use
the contents of the referenced archive as the module source code:

```hcl
module "vpc" {
  source = "https://example.com/vpc-module.zip"
}
```

The extensions that OpenTofu recognizes for this special behavior are:

- `zip`
- `tar.bz2` and `tbz2`
- `tar.gz` and `tgz`
- `tar.xz` and `txz`

If your URL _doesn't_ have one of these extensions but refers to an archive
anyway, use the `archive` argument to force this interpretation:

```hcl
module "vpc" {
  source = "https://example.com/vpc-module?archive=zip"
}
```

:::note
If the content of the archive file is a directory, you will need to
include that directory in the module source. Read the section on
[Modules in Package Sub-directories](#modules-in-package-sub-directories) for more
information.
:::

## S3 Bucket

You can use archives stored in S3 as module sources using the special `s3::`
prefix, followed by
[an S3 bucket object URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucket.html).

```hcl
module "consul" {
  source = "s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/vpc.zip"
}
```

:::note
Buckets in AWS's us-east-1 region must use the hostname `s3.amazonaws.com` (instead of `s3-us-east-1.amazonaws.com`).
:::

The `s3::` prefix causes OpenTofu to use AWS-style authentication when
accessing the given URL. As a result, this scheme may also work for other
services that mimic the S3 API, as long as they handle authentication in the
same way as AWS.

The resulting object must be an archive with one of the same file
extensions as for [archives over standard HTTP](#fetching-archives-over-http).
OpenTofu will extract the archive to obtain the module source tree.

The module installer searches for AWS credentials in a similar way to AWS CLI,
and so you should not typically need any additional configuration to use S3
module sources as long as AWS CLI on your system would be able to access the
same S3 objects.

## GCS Bucket

You can use archives stored in Google Cloud Storage as module sources using the special `gcs::`
prefix, followed by
[a GCS bucket object URL](https://cloud.google.com/storage/docs/request-endpoints#typical).

For example

- `gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH_TO_MODULE`
- `gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH/TO/module.zip`

```hcl
module "consul" {
  source = "gcs::https://www.googleapis.com/storage/v1/modules/foomodule.zip"
}
```

The module installer uses Google Cloud SDK to authenticate with GCS. You can
use any of the following methods to set Google Cloud Platform credentials:

* Set the `GOOGLE_OAUTH_ACCESS_TOKEN` environment variable to a raw Google Cloud Platform OAuth access token.
* Enter the path of your service account key file in the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
* If you're running OpenTofu from a GCE instance, default credentials are automatically available. See [Creating and Enabling Service Accounts](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) for Instances for more details.
* On your computer, you can make your Google identity available by running `gcloud auth application-default login`.

## Modules in Package Sub-directories

When the source of a module is a version control repository or archive file
(generically, a "package"), the module itself may be in a sub-directory relative
to the root of the package.

A special double-slash syntax is interpreted by OpenTofu to indicate that
the remaining path after that point is a sub-directory within the package.
For example:

- `hashicorp/consul/aws//modules/consul-cluster`
- `git::https://example.com/network.git//modules/vpc`
- `oci://example.com/repository-name//modules/vpc`
- `https://example.com/network-module.zip//modules/vpc`
- `s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/network.zip//modules/vpc`

If the source address has arguments, such as the `ref` argument supported for
the version control sources, the sub-directory portion must be _before_ those
arguments:

- `git::https://example.com/network.git//modules/vpc?ref=v1.2.0`
- `github.com/hashicorp/example//modules/vpc?ref=v1.2.0`
- `oci://example.com/repository-name//modules/vpc?tag=v1.2.0`

OpenTofu will still extract the entire package to local disk, but will read
the module from the subdirectory. As a result, it is safe for a module in
a sub-directory of a package to use [a local path](#local-paths) to another
module as long as it is in the _same_ package.

## Support for Variable and Local Evaluation

As projects grow in complexity and requirements, it is prudent to consider using locals and variables in the module source and version fields.

Many organizations utilize the mono-repo pattern for modules:
```hcl
locals {
	modules_repo = "github.com/myorg/tofu-modules/"
	modules_version = "?ref=v1.20.4"
}

module "storage" {
  source = "${local.modules_repo}/storage${local.modules_version}"
}

module "compute" {
  source = "${local.modules_repo}/compute${local.modules_version}"
}
```
It is quite easy to then update the version for a patch release, or to switch to a fork of the repository.

:::note
The source and version fields may not contain any references to data in the state or provider defined functions. All values must be able to be resolved during `tofu init` before the state is available.
:::