---
description: >-
  Providers are plugins that allow OpenTofu to interact with services, cloud
  providers, and other APIs. Learn how to declare providers in a configuration.
---

# Provider Requirements

OpenTofu relies on plugins called "providers" to interact with remote systems.
OpenTofu configurations must declare which providers they require, so that
OpenTofu can install and use them. This page documents how to declare providers
so OpenTofu can install them.

Additionally, some providers require configuration (like endpoint URLs or cloud
regions) before they can be used. The
[Provider Configuration](../../language/providers/configuration.mdx) page
documents how to configure settings for providers.

## Requiring Providers

Each module must declare which providers it requires, so that
OpenTofu can install and use them. Provider requirements are declared in a
`required_providers` block.

A provider requirement consists of a local name, 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 the top-level
[`terraform` block](../../language/settings/index.mdx) (which can also contain other settings).

Each argument in the `required_providers` block enables one provider. The key
determines the provider's [local name](#local-names) (its unique identifier
within this module), and the value is an object with the following elements:

* `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.

## Names and Addresses

Each provider has two identifiers:

* A unique _source address,_ which is only used when requiring a provider.
* A _local name,_ which is used everywhere else in a module.

### Local Names

Local names are module-specific, and are assigned when requiring a provider.
Local names must be unique per-module.

Outside of the `required_providers` block, OpenTofu configurations always refer
to providers by their local names. For example, the following configuration
declares `mycloud` as the local name for `mycorp/mycloud`, then uses that local
name when [configuring the provider](../../language/providers/configuration.mdx):

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

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

Users of a provider can choose any local name for it. However, nearly every
provider has a _preferred local name,_ which it uses as a prefix for all of its
resource types. (For example, resources from `hashicorp/aws` all begin with
`aws`, like `aws_instance` or `aws_security_group`.)

Whenever possible, you should use a provider's preferred local name. This makes
your configurations easier to understand, and lets you omit the `provider`
meta-argument from most of your resources. (If a resource doesn't specify which
provider configuration to use, OpenTofu interprets the first word of the
resource type as a local provider name.)

### Source Addresses

A provider's source address is its global identifier. It also specifies the
primary location where OpenTofu can download it.

Source addresses consist of three parts delimited by slashes (`/`), as
follows:

`[<HOSTNAME>/]<NAMESPACE>/<TYPE>`

* **Hostname** (optional): The hostname of the registry that
  distributes the provider. If omitted, this defaults to
  `registry.opentofu.org`.

* **Namespace:** An organizational namespace within the specified registry.
  In most cases this represents the organization that publishes the provider.
  This field may have other meanings for other registry hosts.

* **Type:** A short name for the platform or system the provider manages. Must
  be unique within a particular namespace on a particular registry host.

  The type is usually the provider's preferred local name. (There are
  exceptions; for example, `hashicorp/google-beta`
  is an alternate release channel for `hashicorp/google`, so its preferred
  local name is `google`. If in doubt, check the provider's documentation.)

For example,
[the official HTTP provider](https://github.com/hashicorp/terraform-provider-http)
belongs to the `hashicorp` namespace on `registry.opentofu.org`, so its
source address is `registry.opentofu.org/hashicorp/http` or, more commonly, just
`hashicorp/http`.

The source address with all three components given explicitly is called the
provider's _fully-qualified address_. You will see fully-qualified address in
various outputs, like error messages, but in most cases a simplified display
version is used. This display version omits the source host when it is the
public registry, so you may see the shortened version `"hashicorp/random"` instead
of `"registry.opentofu.org/hashicorp/random"`.

:::note
If you omit the `source` argument when requiring a provider,
OpenTofu uses an implied source address of
`registry.opentofu.org/hashicorp/<LOCAL NAME>`.
We recommend using explicit source addresses for all providers.
:::

### Handling Local Name Conflicts

Whenever possible, we recommend using a provider's preferred local name, which
is usually the same as the "type" portion of its source address.

However, it's sometimes necessary to use two providers with the same preferred
local name in the same module, usually when the providers are named after a
generic infrastructure type. OpenTofu requires unique local names for each
provider in a module, so you'll need to use a non-preferred name for at least
one of them.

When this happens, we recommend combining each provider's namespace with
its type name to produce compound local names with a dash:

```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" {
  # ...
}

data "http" "example" {
  provider = hashicorp-http
  #...
}
```

OpenTofu won't be able to guess either provider's name from its resource types,
so you'll need to specify a `provider` meta-argument for every affected
resource. However, readers and maintainers of your module will be able to easily
understand what's happening, and avoiding confusion is much more important than
avoiding typing.

## Version Constraints

Each provider plugin has its own set of available versions, allowing the
functionality of the provider to evolve over time. Each provider dependency you
declare should have a [version constraint](../../language/expressions/version-constraints.mdx) given in
the `version` argument so OpenTofu can select a single version per provider
that all modules are compatible with.

The `version` argument is optional; if omitted, OpenTofu will accept any
version of the provider as compatible. However, we strongly recommend specifying
a version constraint for every provider your module depends on.

To ensure OpenTofu always installs the same provider versions for a given
configuration, you can use OpenTofu CLI to create a
[dependency lock file](../../language/files/dependency-lock.mdx)
and commit it to version control along with your configuration. If a lock file
is present, OpenTofu CLI, and [TACOS](../../intro/tacos.mdx) (TF Automation and Collaboration Software) will all obey it when
installing providers.

### Best Practices for Provider Versions

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

```hcl
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 `tofu apply` — should also specify the
_maximum_ provider version it is intended to work with, to avoid accidental
upgrades to incompatible new versions. The `~>` operator is a convenient
shorthand for allowing the rightmost component of a version to increment. The
following example uses the operator to allow only patch releases within a
specific minor release:

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

Do not use `~>` (or other maximum-version constraints) for modules you intend to
reuse across many configurations, even if you know the module isn't compatible
with certain newer versions. Doing so can sometimes prevent errors, but more
often it forces users of the module to update many modules simultaneously when
performing routine upgrades. Specify a minimum version, document any known
incompatibilities, and let the root module manage the maximum version.

## Built-in Providers

Most providers are distributed separately as plugins, but there
is one provider that is built into OpenTofu itself. This provider enables the
[the `terraform_remote_state` data source](../../language/state/remote-state-data.mdx).

Because this provider is built in to OpenTofu, 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
OpenTofu'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 "tofu".

There is also an existing provider with the source address
`hashicorp/terraform`, which is an older version of the now-built-in provider.
`hashicorp/terraform` is not compatible with OpenTofu and should never be declared in a
`required_providers` block.

## In-house Providers

Anyone can develop and distribute their own providers.

Some organizations develop their own providers to configure
proprietary systems, and wish to use these providers from OpenTofu without
publishing them on a registry.

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

Running an additional service just to distribute a single provider internally
may be undesirable, so OpenTofu also supports
[other provider installation methods](../../cli/config/config-file.mdx#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 registry, but that hostname does not need to
provide an actual registry service. For in-house providers that you intend to
distribute from a local filesystem directory, you can use an arbitrary hostname
in a domain your organization controls.

For example, if your corporate domain were `example.com` then you might choose
to use `tofu.example.com` as your placeholder 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 `tofu.example.com/examplecorp/ourcloud`:

```hcl
terraform {
  required_providers {
    mycloud = {
      source  = "tofu.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](../../cli/config/config-file.mdx#implied-local-mirror-directories)
and create a directory structure under it like this:

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

Under that `1.0.0` directory, create one additional directory representing the
platform where you are running OpenTofu, 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.

Thus, on a Windows system, the provider plugin executable file might be at the
following path:

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

If you later decide to switch to using a real private provider registry rather
than distribute binaries out of band, you can deploy the registry server at
`tofu.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.
