packer/website/content/docs/plugins/install-plugins.mdx

---
description: |
  Install external Packer plugins that extend Packer functionality.
page_title: Install Plugins
---

# Installing Plugins

Packer plugins are separate, standalone applications that perform tasks during each build.

You do not need to install the builder, provisioner, or
post-processor components that ship with the Packer binary. Packer automatically knows how to find and launch these built-in plugins.

This page explains how to install custom external plugins. Refer to [External Plugins](/packer/plugins) for a list of available plugins and their documentation.

## Plugin Loading Order

@include "plugins/plugin-location.mdx"

## Installation Guides

<Tabs>
<Tab heading="Packer init (recommended with HCL2 templates)">

-> **Note:** Only _multi-component plugin binaries_ -- plugins named
packer-plugin-\*, like the `packer-plugin-amazon` -- are expected to work with
Packer init. The legacy `builder`, `post-processor` and `provisioner` plugin
types will continue to be detected but Packer cannot install them automatically.
If a plugin you use has not been upgraded to use the multi-component plugin
architecture, contact your maintainer to request an upgrade.

## Create a required_plugins block

1. Add a
   [`required_plugins`](/packer/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements)
   block to your [packer block](/packer/docs/templates/hcl_templates/blocks/packer). Each block will tell Packer what version(s) of a
   particular plugin can be installed. Make sure to set a valid [version
   constraint string](/packer/docs/templates/hcl_templates/blocks/packer#version-constraints).

Here is an example `required_plugins` block:

```hcl
packer {
  required_plugins {
    myawesomecloud = {
      version = ">= 2.7.0"
      source = "github.com/azr/myawesomecloud"
    }
    happycloud = {
      version = ">= 1.1.3"
      source = "github.com/azr/happycloud"
    }
  }
}
```

2. Run [`packer init`](/packer/docs/commands/init) from your project directory (the
   directory containing your Packer templates) to install all missing plugin
   binaries. Given the above example, Packer will try to look for a GitHub
   repository owned by user or organization `azr` named
   `packer-plugin-myawesomecloud` and `packer-plugin-happycloud`.

## Names and Addresses

Each plugin has two identifiers:

- A `source` address, which is necessary when requiring a plugin not bundled with the Packer binary.
- A unique **local name**, which is used everywhere else in a Packer configuration.

## Local Names

Local names allow you to access the components of a plugin and must be unique
per configuration.

This is best explained using an example. In the above `required_plugins` block,
we declared the local name "myawesomecloud" for the plugin `azr/myawesomecloud`.
If the "myawesomecloud" plugin contains both an "ebs" builder and an "import"
post-processor, then the builder will be accessed in a source block by using:

```hcl
source "myawesomecloud-ebs" "example" {
  // builder configuration...
}
```

similarly, the import post-processor would be accessed by declaring the
post-processor block:

```hcl
post-processor "myawesomecloud-import" {
  // post-processor configuration...
}
```

If we change the required_plugins block to use a different local name "foo":

```hcl
  required_plugins {
    foo = {
      version = ">= 2.7.0"
      source = "github.com/azr/myawesomecloud"
    }
  }
```

Then we'd instead access that builder using the source:

```hcl
source "foo-ebs" "example" {
  // builder configuration...
}
```

## Source Addresses

A plugin's source address is its global identifier. It also tells Packer where
to download it.

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

`<HOSTNAME>/<NAMESPACE>/<TYPE>`

- **Hostname:** The hostname of the location/service that
  distributes the plugin. Currently, the only valid "hostname" is github.com,
  but we plan to eventually support plugins downloaded from other domains.

- **Namespace:** An organizational namespace within the specified host.
  This often is the organization that publishes the plugin.

- **Type:** A short name for the platform or system the plugin manages. The
  type is usually the plugin's preferred local name.

For example, the fictional `myawesomecloud` plugin could belong to the
`hashicorp` namespace on `github.com`, so its `source` could be
`github.com/hashicorp/myawesomecloud`,

-> Note: the actual _repository_ that myawesomecloud comes from must always have
the name format `github.com/hashicorp/packer-plugin-myawesomecloud`, but the
`required_plugins` block omits the redundant `packer-plugin-` repository prefix
for brevity.

The source address with all three components given explicitly is called the
plugin's _fully-qualified address_. You will see fully-qualified address in
various outputs, like error messages.

## Plugin Installation Workflow

* [`packer init`](/packer/docs/commands/init) will install plugins in the **last** directory
in the following numbered list.

1. `PACKER_PLUGIN_PATH` if set will be the sole location for installing plugins. All other
plugin directories will be ignored.
1. `PACKER_CONFIG_DIR`\plugins on Windows systems, or `PACKER_CONFIG_DIR`/plugins on all other systems.

* During the initialization of Packer, any plugin required in the
**`required_plugins`** section will be looked up in all entries of the following
list. **First** plugin found takes precedence. Two binaries of the same plugin
with two different version will be considered as two different plugins. Highest
found version matching `required_plugins` will be taken into consideration.

During initialization, on a `darwin_amd64` system, Packer will look-up for the
following files:

* `PACKER_PLUGIN_PATH/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64`
* `PACKER_CONFIG_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64`

The first plugin-name/version files found will take precedence.

For plugins located under the `github.com/azr/happycloud/` directory structure an accompanying SHA256SUM file
will be required in order for `packer init` to ensure the plugin being loaded has not been tampered with.
The SHA256SUM file will be automatically generated when a plugin is installed via `packer init` if the plugin
was installed manually into `PACKER_CONFIG_DIR/plugins/github.com/azr/happycloud/` then the file
`PACKER_CONFIG_DIR/plugins/github.com/azr/happycloud/packer-plugin-happycloud_*_x5.0_darwin_amd64_SHA256SUM` must be generated manually as well.

</Tab>
<Tab heading="Packer plugins install (recommended with legacy JSON templates)">

Plugin installation via `packer plugins install` works similar to that of the `packer init` command, with the following
exceptions no `required_plugins` block required and can be used with both legacy JSON and HCL2 templates.

-> The [`packer plugins`](/packer/docs/commands/plugins), available from Packer v1.8.0, command allows
you to install plugins without going through `init`.

```shell
packer plugins install github.com/hashicorp/vagrant
```

The command will install the plugin in the `PACKER_CONFIG_DIR` set, or its
default location, which depends on the OS/environment, as documented in
[Configuring Packer](https://developer.hashicorp.com/packer/docs/configure#packer-s-plugin-directory).

</Tab>
<Tab heading="Manual installation">

If you have obtained or built a plugin binary for your OS/Architecture and want to
use it with Packer, you can install it manually. For Packer to load the plugin,
it must be named with the convention `packer-plugin-NAME`, and placed in Packer's plugin
directory, as documented in
[Configuring Packer](https://developer.hashicorp.com/packer/docs/configure#packer-s-plugin-directory).

For example, if your configuration directory is located in `~/.config/packer`,
you can copy the binary to `~/.config/plugins/packer-plugin-NAME`, and
Packer will be able to load it afterwards.

</Tab>
</Tabs>