<commit_before>---
layout: "docs"
page_title: "Module Sources"
sidebar_current: "docs-modules-sources"
description: Explains the use of the source parameter, which tells Terraform where modules can be found.
---

# Module Sources

As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`.

The `source` parameter tells Terraform where the module can be found.
Terraform manages modules for you: it downloads them, organizes them on disk, checks for updates, etc. Terraform uses this `source` parameter to determine where it should retrieve and update modules from.

Terraform supports the following sources:

  * [Local file paths](#local-file-paths)

  * [Terraform Registry](#terraform-registry)

  * [GitHub](#github)

  * [Bitbucket](#bitbucket)

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

  * [HTTP URLs](#http-urls)

  * [S3 buckets](#s3-bucket)

Each is documented further below.

## Local File Paths

The easiest source is the local file path. For maximum portability, this should be a relative file path into a subdirectory. This allows you to organize your Terraform configuration into modules within one repository, for example:

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

Updates for file paths are automatic: when "downloading" the module using the [get command](/docs/commands/get.html), Terraform will create a symbolic link to the original directory. Therefore, any changes are automatically available.

## Terraform Registry

The [Terraform Registry](https://registry.terraform.io) is an index of modules
written by the Terraform community.
The Terraform Registry is the easiest
way to get started with Terraform and to find modules.

The registry is integrated directly into Terraform. You can reference any
registry module with a source string of `<NAMESPACE>/<NAME>/<PROVIDER>`. Each
module's information page on the registry includes its source string.

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

The above example would use the
[Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws)
from the public registry.

Registry modules support versioning. You can provide a specific version, or use
flexible [version constraints](/docs/modules/usage.html#module-versions).

You can learn more about the registry at the
[Terraform Registry documentation](/docs/registry/modules/use.html#using-modules).

## Private Registries

[Terraform Enterprise](https://www.hashicorp.com/products/terraform) provides a
[private module registry](/docs/enterprise/registry/index.html), to help
you share code within your organization. Other services can also provide
private registries by implementing [Terraform's registry API](/docs/registry/api.html).

Source strings for private registry modules are similar to public modules, but
also include a hostname. They should follow the format
`<HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>`.

```hcl
module "vpc" {
  source = "app.terraform.io/example_corp/vpc/aws"
  version = "0.9.3"
}
```

Modules from private registries support versioning, just like modules from the
public Terraform Registry.

## GitHub

Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple:

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

Subdirectories within the repository can also be referenced:

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

These will fetch the modules using HTTPS.  If you want to use SSH instead:

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

**Note:** The double-slash, `//`, is important. It is what tells Terraform that that is the separator for a subdirectory, and not part of the repository itself.

GitHub source URLs require that Git is installed on your system and that you have access to the repository.

You can use the same parameters to GitHub repositories as you can generic Git repositories (such as tags or branches). See [the documentation for generic Git repositories](#parameters) for more information.

### Private GitHub Repos

If you need Terraform to fetch modules from private GitHub repos, you must provide Terraform with credentials to authenticate as a user with read access to those repos.

- If you run Terraform only on your local machine, you can specify the module source as an SSH URI (like `git@github.com:hashicorp/example.git`) and Terraform will use your default SSH key to authenticate.
- If you use Terraform Enterprise, consider using the private module registry. It makes handling credentials easier, and provides full versioning support. (See [Private Registries](#private-registries) above for more info.)

    If you need to use modules directly from Git, you can use SSH URIs with Terraform Enterprise. You'll need to add an SSH private key to your organization and assign it to any workspace that fetches modules from private repos. [See the Terraform Enterprise docs about SSH keys for cloning modules.](/docs/enterprise/workspaces/ssh-keys.html)
- If you need to run Terraform on a remote machine like a CI worker, you either need to write an SSH key to disk and set the `GIT_SSH_COMMAND` environment variable appropriately during the worker's provisioning process, or create a [GitHub machine user](https://developer.github.com/guides/managing-deploy-keys/#machine-users) with read access to the repos in question and embed its credentials into the modules' `source` parameters:

    ```hcl
    module "private-infra" {
      source = "git::https://MACHINE-USER:MACHINE-PASS@github.com/org/privatemodules//modules/foo"
    }
    ```

    Note that Terraform does not support interpolations in the `source` parameter of a module, so you must hardcode the machine username and password if using this method.

## Bitbucket

Terraform will automatically recognize public Bitbucket URLs and turn them into a link to the specific Git or Mercurial repository, for example:

```hcl
module "consul" {
  source = "bitbucket.org/hashicorp/consul"
}
```

Subdirectories within the repository can also be referenced:

```hcl
module "consul" {
  source = "bitbucket.org/hashicorp/consul//subdir"
}
```

**Note:** The double-slash, `//`, is important. It is what tells Terraform that this is the separator for a subdirectory, and not part of the repository itself.

Bitbucket URLs will require that Git or Mercurial is installed on your system, depending on the type of repository.

## Private Bitbucket Repos
Private bitbucket repositories must be specified similar to the [Generic Git Repository](#generic-git-repository) section below.

```hcl
module "consul" {
  source = "git::https://bitbucket.org/foocompany/module_name.git"
}
```

You can also specify branches and version withs the ?ref query

```hcl
module "consul" {
  source = "git::https://bitbucket.org/foocompany/module_name.git?ref=hotfix"
}
```

You will need to run a `terraform get -update=true` if you want to pull the latest versions. This can be handy when you are rapidly iterating on a module in development.

## Generic Git Repository

Generic Git repositories are also supported. The value of `source` in this case should be a complete Git-compatible URL. Using generic Git repositories requires that Git is installed on your system.

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

You can also use protocols such as HTTP or SSH to reference a module, but you'll have specify to Terraform that it is a Git module, by prefixing the URL with `git::` like so:

```hcl<commit_msg>website: Example of the Git+SSH protocol for bitbucket module sources<commit_after>---
layout: "docs"
page_title: "Module Sources"
sidebar_current: "docs-modules-sources"
description: Explains the use of the source parameter, which tells Terraform where modules can be found.
---

# Module Sources

As documented in the [Usage section](/docs/modules/usage.html), the only required parameter when using a module is `source`.

The `source` parameter tells Terraform where the module can be found.
Terraform manages modules for you: it downloads them, organizes them on disk, checks for updates, etc. Terraform uses this `source` parameter to determine where it should retrieve and update modules from.

Terraform supports the following sources:

  * [Local file paths](#local-file-paths)

  * [Terraform Registry](#terraform-registry)

  * [GitHub](#github)

  * [Bitbucket](#bitbucket)

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

  * [HTTP URLs](#http-urls)

  * [S3 buckets](#s3-bucket)

Each is documented further below.

## Local File Paths

The easiest source is the local file path. For maximum portability, this should be a relative file path into a subdirectory. This allows you to organize your Terraform configuration into modules within one repository, for example:

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

Updates for file paths are automatic: when "downloading" the module using the [get command](/docs/commands/get.html), Terraform will create a symbolic link to the original directory. Therefore, any changes are automatically available.

## Terraform Registry

The [Terraform Registry](https://registry.terraform.io) is an index of modules
written by the Terraform community.
The Terraform Registry is the easiest
way to get started with Terraform and to find modules.

The registry is integrated directly into Terraform. You can reference any
registry module with a source string of `<NAMESPACE>/<NAME>/<PROVIDER>`. Each
module's information page on the registry includes its source string.

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

The above example would use the
[Consul module for AWS](https://registry.terraform.io/modules/hashicorp/consul/aws)
from the public registry.

Registry modules support versioning. You can provide a specific version, or use
flexible [version constraints](/docs/modules/usage.html#module-versions).

You can learn more about the registry at the
[Terraform Registry documentation](/docs/registry/modules/use.html#using-modules).

## Private Registries

[Terraform Enterprise](https://www.hashicorp.com/products/terraform) provides a
[private module registry](/docs/enterprise/registry/index.html), to help
you share code within your organization. Other services can also provide
private registries by implementing [Terraform's registry API](/docs/registry/api.html).

Source strings for private registry modules are similar to public modules, but
also include a hostname. They should follow the format
`<HOSTNAME>/<NAMESPACE>/<NAME>/<PROVIDER>`.

```hcl
module "vpc" {
  source = "app.terraform.io/example_corp/vpc/aws"
  version = "0.9.3"
}
```

Modules from private registries support versioning, just like modules from the
public Terraform Registry.

## GitHub

Terraform will automatically recognize GitHub URLs and turn them into a link to the specific Git repository. The syntax is simple:

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

Subdirectories within the repository can also be referenced:

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

These will fetch the modules using HTTPS.  If you want to use SSH instead:

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

**Note:** The double-slash, `//`, is important. It is what tells Terraform that that is the separator for a subdirectory, and not part of the repository itself.

GitHub source URLs require that Git is installed on your system and that you have access to the repository.

You can use the same parameters to GitHub repositories as you can generic Git repositories (such as tags or branches). See [the documentation for generic Git repositories](#parameters) for more information.

### Private GitHub Repos

If you need Terraform to fetch modules from private GitHub repos, you must provide Terraform with credentials to authenticate as a user with read access to those repos.

- If you run Terraform only on your local machine, you can specify the module source as an SSH URI (like `git@github.com:hashicorp/example.git`) and Terraform will use your default SSH key to authenticate.
- If you use Terraform Enterprise, consider using the private module registry. It makes handling credentials easier, and provides full versioning support. (See [Private Registries](#private-registries) above for more info.)

    If you need to use modules directly from Git, you can use SSH URIs with Terraform Enterprise. You'll need to add an SSH private key to your organization and assign it to any workspace that fetches modules from private repos. [See the Terraform Enterprise docs about SSH keys for cloning modules.](/docs/enterprise/workspaces/ssh-keys.html)
- If you need to run Terraform on a remote machine like a CI worker, you either need to write an SSH key to disk and set the `GIT_SSH_COMMAND` environment variable appropriately during the worker's provisioning process, or create a [GitHub machine user](https://developer.github.com/guides/managing-deploy-keys/#machine-users) with read access to the repos in question and embed its credentials into the modules' `source` parameters:

    ```hcl
    module "private-infra" {
      source = "git::https://MACHINE-USER:MACHINE-PASS@github.com/org/privatemodules//modules/foo"
    }
    ```

    Note that Terraform does not support interpolations in the `source` parameter of a module, so you must hardcode the machine username and password if using this method.

## Bitbucket

Terraform will automatically recognize public Bitbucket URLs and turn them into a link to the specific Git or Mercurial repository, for example:

```hcl
module "consul" {
  source = "bitbucket.org/hashicorp/consul"
}
```

Subdirectories within the repository can also be referenced:

```hcl
module "consul" {
  source = "bitbucket.org/hashicorp/consul//subdir"
}
```

**Note:** The double-slash, `//`, is important. It is what tells Terraform that this is the separator for a subdirectory, and not part of the repository itself.

Bitbucket URLs will require that Git or Mercurial is installed on your system, depending on the type of repository.

## Private Bitbucket Repos
Private bitbucket repositories must be specified similar to the [Generic Git Repository](#generic-git-repository) section below.

```hcl
module "consul" {
  source = "git::https://bitbucket.org/foocompany/module_name.git"
}
```

You can also specify branches and version with the `?ref` query, and use HTTPS or SSH:

```hcl
module "consul" {
  source = "git::https://bitbucket.org/foocompany/module_name.git?ref=hotfix"
}
```

```hcl
module "consul" {
  source = "git::ssh://git@bitbucket.org/foocompany/module_name.git"
}
```

You will need to run a `terraform get -update=true` if you want to pull the latest versions. This can be handy when you are rapidly iterating on a module in development.

## Generic Git Repository

Generic Git repositories are also supported. The value of `source` in this case should be a complete Git-compatible URL. Using generic Git repositories requires that Git is installed on your system.

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

You can also use protocols such as HTTP or SSH to reference a module, but you'll have specify to Terraform that it is a Git module, by prefixing the URL with `git::` like so:

```hcl
{'fraction_non_alphanumeric': 0.08505072417533338, 'fraction_numerical': 0.0010208639060805206, 'mean_word_length': 4.644220381706878, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 14, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 7, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5617943', 'n_tokens_mistral': 4460, 'n_tokens_neox': 4225, 'n_words': 1932}