terraform/website/docs/configuration/provider-requirements.html.md

---
layout: "docs"
page_title: "Provider Requirements - Configuration Language"
---

## Provider Requirements

-> **Note:** If you are using Terraform 0.11 or
earlier, see
[0.11 Configuration Language: Provider Versions](../configuration-0-11/providers.html#provider-versions) instead.

Terraform relies on plugins called "providers" to interact with remote systems.
Each provider offers a set of named
[resource types](resources.html#resource-types-and-arguments), and defines for
each resource type which arguments it accepts, which attributes it exports, and
how changes to resources of that type are actually applied to remote APIs.

You can discover publicly-available providers
[via the Terraform Registry](https://registry.terraform.io/browse/providers).
Which providers you will use will depend on which remote cloud services you are
intending to configure. Additionally, some Terraform providers provide
local-only functionality which is useful to integrate functionality offered by
different providers, such as generating random numbers to help construct
unique resource names.

Once you've selected one or more providers, use a `required_providers` block to
declare them so that Terraform will make them available for use. A provider
dependency consists of both a source location and a version constraint:

```hcl
terraform {
  required_providers {
    mycloud = {
      source  = "mycorp/mycloud"
      version = "~> 1.0"
    }
  }
}
```

The `required_providers` block must be nested inside a
[`terraform` block](terraform.html). The `terraform` block can include other
settings too, but we'll only focus on `required_providers` here.

The keys inside the `required_providers` block represent each provider's
[local name](#local-names), which is the unique identifier for a provider within
a particular module. Each item inside the `required_providers` block is an
object expecting the following arguments:

* `source` - the global [source address](#source-addresses) for the
  provider you intend to use, such as `hashicorp/aws`.

* `version` - a [version constraint](#version-constraints) specifying
  which subset of available provider versions the module is compatible with.

-> **Note:** The `required_providers` object syntax described above was added in Terraform v0.13. Previous versions of Terraform used a single string instead of an object, with the string specifying only a version constraint. For example, `mycloud = "~> 1.0"`. Explicit provider source addresses are supported only in Terraform v0.13 and later. If you want to write a module that works with both Terraform v0.12 and v0.13, see [v0.12-Compatible Provider Requirements](#v012-compatible-provider-requirements) below.

### Source Addresses

A provider _source address_ both globally identifies a particular provider and
specifies the primary location from which Terraform can download it.
Source addresses consist of three parts delimited by slashes (`/`), as
follows:

* **Hostname**: the hostname of the Terraform registry that indexes the provider.
  You can omit the hostname portion and its following slash if the provider
  is hosted on [the public Terraform Registry](https://registry.terraform.io/),
  whose hostname is `registry.terraform.io`.

* **Namespace**: an organizational namespace within the specified registry.
  For the public Terraform Registry and Terraform Cloud's private registry,
  this represents the organization that is publishing the provider. This field
  may have other meanings for other registry hosts.

* **Type**: The provider type name, which must be unique within a particular
  namespace on a particular registry host.

For example,
[the official HTTP provider](https://registry.terraform.io/providers/hashicorp/http)
belongs to the `hashicorp` namespace on `registry.terraform.io`, so its
source address can be written as either `registry.terraform.io/hashicorp/http`
or, more commonly, just `hashicorp/http`.

-> **Note**: As a concession for backward compatibility with earlier versions of
Terraform, the `source` argument is actually optional. If you omit it, Terraform
will construct an implied source address by appending the local name to the prefix
`hashicorp/`. For example, a provider dependency with local name `http` that
does not have an explicit `source` will be treated as equivalent to
`hashicorp/http`. We recommend using explicit source addresses for all providers
in modules that require Terraform 0.13 or later, so a future reader of your
module can clearly see exactly which provider is required, without needing to
first understand this default behavior.

### Local Names

Full [source addresses](#source-addresses) are verbose, so the Terraform
language uses them only when declaring dependencies. We associate each required
provider with a module-specific _local name_, which is a short identifier that
will refer to the associated source address within declarations inside a
particular module.

```hcl
terraform {
  required_providers {
    mycloud = {
      source  = "mycorp/mycloud"
      version = "~> 1.0"
    }
  }
}
```

The above example declares `mycloud` as the local name for `mycorp/mycloud`
(which is short for `registry.terraform.io/mycorp/mycloud`) in the current
module only. That means we will refer to this provider as `mycloud` elsewhere
in the module, such as in a `provider "mycloud"` block used to create a
[provider configuration](providers.html):

```hcl
provider "mycloud" {
  # ...
}
```

We strongly recommend setting the local name of a provider to match the "type"
portion of its source address, as in the above example. Consistent use of the
provider's canonical type can help avoid the need for readers of the rest of
the module to refer to the `required_providers` block to understand which
provider the module is using.

The one situation where it is reasonable to use a different local name is the
relatively-rare case of having two providers in the same module that have the
same type name. In that case, Terraform requires choosing a unique local name
for each one. In that situation, we recommend to combine the namespace with
the type name to produce a compound local name to disambiguate:

```hcl
terraform {
  required_providers {
    # In the rare situation of using two providers that
    # have the same type name -- "http" in this example --
    # use a compound local name to distinguish them.
    hashicorp_http = {
      source  = "hashicorp/http"
      version = "~> 2.0"
    }
    mycorp_http = {
      source  = "mycorp/http"
      version = "~> 1.0"
    }
  }
}

# References to these providers elsewhere in the
# module will use these compound local names.
provider "mycorp_http" {
  # ...
}
```

### Version Constraints

A [source address](#source-addresses) uniquely identifies a particular
provider, but each provider can have one or more distinct _versions_, allowing
the functionality of the provider to evolve over time. Each provider dependency
you declare should have a [version constraint](./version-constraints.html)
given in the `version` argument.

Each module should at least declare the minimum provider version it is known
to work with, using the `>=` version constraint syntax:

```
terraform {
  required_providers {
    mycloud = {
      source  = "hashicorp/aws"
      version = ">= 1.0"
    }
  }
}
```

A module intended to be used as the root of a configuration -- that is, as the
directory where you'd run `terraform apply` -- should also specify the
_maximum_ provider version it is intended to work with, to avoid accidental
upgrading when new versions are released. The `~>` operator is a convenient
shorthand for allowing only patch releases within a specific minor release:

```
terraform {
  required_providers {
    mycloud = {
      source  = "hashicorp/aws"
      version = "~> 1.0.4"
    }
  }
}
```

_Do not_ use the `~>` or other maximum-version constraints for modules you
intend to reuse across many configurations. All of the version constraints
across all modules in a configuration must work collectively to select a
single version to use, so many modules all specifying maximum version
constraints would require those upper limits to all be updated simultaneously
if one module begins requiring a newer provider version.

The `version` argument is optional. If you omit it, Terraform will accept
_any_ version of the provider as compatible. That's risky for a provider
distributed by a third-party, because they may release a version containing
breaking changes at any time and prevent you from making progress until you
update your configuration. We strongly recommend always specifying a version
constraint, as described above, for every provider your module depends on.

### Built-in Providers

While most Terraform providers are distributed separately as plugins, there
is currently one provider that is built in to Terraform itself, which
provides
[the `terraform_remote_state` data source](/docs/providers/terraform/d/remote_state.html).

Because this provider is built in to Terraform, you don't need to declare it
in the `required_providers` block in order to use its features. However, for
consistency it _does_ have a special provider source address, which is
`terraform.io/builtin/terraform`. This address may sometimes appear in
Terraform's error messages and other output in order to unambiguously refer
to the built-in provider, as opposed to a hypothetical third-party provider
with the type name "terraform".

There is also an existing provider with the source address
`hashicorp/terraform`, which is an older version of the now-built-in provider
that was used by older versions of Terraform. `hashicorp/terraform` is not
compatible with Terraform v0.11 or later and should never be declared in a
`required_providers` block.

### In-house Providers

Some organizations develop their own providers to allow interacting with
proprietary systems, and wish to use these providers from Terraform without
publishing them on the public Terraform Registry.

One option for distributing such a provider is to run an in-house _private_
registry, by implementing
[the provider registry protocol](/docs/internals/provider-registry-protocol.html).

Running an additional service just to distribute a single provider internally
may be undesirable though, so Terraform also supports
[other provider installation methods](https://github.com/hashicorp/terraform/blob/master/website/docs/commands/cli-config.html.markdown#provider-installation),
including placing provider plugins directly in specific directories in the
local filesystem, via _filesystem mirrors_.

All providers must have a [source address](#source-addresses) that includes
(or implies) the hostname of a host registry, but for an in-house provider that
you intend only to distribute from a local filesystem directory you can choose
an artificial hostname in a domain your organization controls and use that to
mark your in-house providers.

For example, if your corporate domain were `example.com` then you might choose
to use `terraform.example.com` as your artificial hostname, even if that
hostname doesn't actually resolve in DNS. You can then choose any namespace and
type you wish to represent your in-house provider under that hostname, giving
a source address like `terraform.example.com/examplecorp/ourcloud`:

```hcl
terraform {
  required_providers {
    mycloud = {
      source  = "terraform.example.com/examplecorp/ourcloud"
      version = ">= 1.0"
    }
  }
}
```

To make version 1.0.0 of this provider available for installation from the
local filesystem, choose one of the
[implied local mirror directories](/docs/commands/cli-config.html#implied-local-mirror-directories)
and create a directory structure under it like this:

```
terraform.example.com/examplecorp/ourcloud/1.0.0
```

Under that `1.0.0` directory, create one additional directory representing the
platform where you are running Terraform, such as `linux_amd64` for Linux on
an AMD64/x64 processor, and then place the provider plugin executable and any
other needed files in that directory.

The provider plugin executable file might therefore be at the following path,
on a Windows system for the sake of example:

```
terraform.example.com/examplecorp/ourcloud/1.0.0/windows_amd64/terraform-provider-ourcloud.exe
```

If you later decide to switch to using a real private provider registry, rather
than an artifical local hostname, you can deploy the registry server at
`terraform.example.com` and retain the same namespace and type names, in which
case your existing modules will require no changes to locate the same provider
using your registry server instead.

### v0.12-Compatible Provider Requirements

Explicit provider source addresses were introduced with Terraform v0.13, so the
full provider requirements syntax is not supported by Terraform v0.12.

However, in order to allow writing modules that are compatible with both
Terraform v0.12 and v0.13 at the same time, later versions of Terraform v0.12
will accept but ignore the `source` argument in a required_providers block.

Consider the following example written for Terraform v0.13:

```hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 1.0"
    }
  }
}
```

Terraform v0.12.26 will accept syntax like the above but will understand it
in the same way as the following v0.12-style syntax:

```hcl
terraform {
  required_providers {
    aws = "~> 1.0"
  }
}
```

In other words, Terraform v0.12.26 ignores the `source` argument and considers
only the `version` argument, using the given [local name](#local-names) as the
un-namespaced provider type to install.

When writing a module that is compatible with both Terraform v0.12.26 and
Terraform v0.13.0 or later, you must follow the following additional rules so
that both versions will select the same provider to install:

* Use only providers that are automatically-installable under Terraform v0.12.
  Third-party providers, such as community providers in the Terraform Registry,
  cannot be selected by Terraform v0.12 because it does not support the
  hierarchical source address namespace.

* Ensure that your chosen local name exactly matches the "type" portion of the
  source address given in the `source` argument, such as both being "aws" in
  the examples above, because Terraform v0.12 will use the local name to
  determine which provider plugin to download and install.

* If the provider belongs to the `hashicorp` namespace, as with the
  `hashicorp/aws` provider shown above, omit the `source` argument and allow
  Terraform v0.13 select the `hashicorp` namespace by default.

* Provider type names must always be written in lowercase. Terraform v0.13
  treats provider source addresses as case-insensitive, but Terraform v0.12
  considers its legacy-style provider names to be case-sensitive. Using
  lowercase will ensure that the name is selectable by both Terraform major
  versions.

This compatibility mechanism is provided as a temporary transitional aid only.
When Terraform v0.12 detects the use of the new `source` argument it doesn't
understand, it will emit a warning to alert the user that it is disregarding
the source address given in that argument.