packer-cn/website/content/docs/plugins/index.mdx

---
description: |
  Packer Plugins allow new functionality to be added to Packer without modifying
  the core source code. Packer plugins are able to add new builders,
  provisioners, hooks, and more.
page_title: Plugins
sidebar_title: Packer Plugins
---

# Packer Plugins

Packer Plugins allow new functionality to be added to Packer without modifying
the core source code. Packer plugins are able to add new builders, provisioners,
hooks, and more. In fact, much of Packer itself is implemented by writing
plugins that are simply distributed with Packer. For example, many of the
builders, provisioners, and more that ship with Packer are implemented as
Plugins that are simply hardcoded to load with Packer.

* This page documents how to install plugins.
* Plugins cannot be configured yet.
* If you're interested in developing plugins, see the [developing 
plugins](/docs/plugins/creation#developing-plugins) page.

The current official listing of available Packer plugins can be found
[here](/community-tools#third-party-plugins). These plugins will need to be
manually installed. This is an incomplete list, and more plugins can be found by
searching. Typically, searching "packer plugin _x_" will find what you're
looking for if it exists. We hope to create an offical registry for third party
plugins in the future.

## How Plugins Work

Packer plugins are completely separate, standalone applications that the core
of Packer starts and communicates with.

These plugin applications aren't meant to be run manually. Instead, Packer core
executes them as a sub-process, run as a sub-command (`packer plugin`) and
communicates with them. For example, the Shell provisioner is actually run as
`packer plugin packer-provisioner-shell`. The next time you run a Packer build,
look at your process list and you should see a handful of `packer-` prefixed
applications running.

## Installing Plugins

<Tabs>
<Tab heading="with Packer init (from Packer v1.7.0)">

~> **Note**: Only _multi-plugin binaries_ -- that is 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 keep on being detected but Packer cannot install them automatically.

## Installing Plugins

1. Add a
[`required_plugin`](/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements)
block to your `packer` block, each block will tell Packer what version(s) can be
installed, make sure to set a correct [version constraint
string](/docs/templates/hcl_templates/blocks/packer#version-constraints). 
  Example `required_plugins` block :

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

2. Run [`packer init`](/docs/commands/init) to install all missing plugin binaries.

## Names and Addresses
Each plugin has two identifiers:

* A `source` address, which is only used when requiring a plugin outside the HashiCorp domain.
* 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.

Here using the previous example if the required plugin `azr/myawesomecloud`
defined an `ebs` builder, this builder will be made available by using a
`myawesomecloud-ebs` source block :

```hcl
source "myawesomecloud-ebs" "example" {...}
```

## Source Addresses

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

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

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

* **Hostname** (optional): The hostname of the location/service that
  distributes the plugin. If omitted, this defaults to
  `github.com`, we recommend explicitly setting the hostname.

* **Namespace:** An organizational namespace within the specified host.
  This often is the organization that publishes the plugin. If omitted, this
  defaults to `hashicorp`, we recommend explicitly setting the namespace.

* **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`, `hashicorp/myawesomecloud` or
`myawesomecloud`.

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, 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 `"myawesomecloud"` instead
of `"github.com/hashicorp/myawesomecloud"`.

-> **Note:** We recommend using explicit source addresses for all plugins.

## Plugin location

@include "plugins/plugin-location.mdx"

## Implicit Github urls

Using the following example :
```hcl
    required_plugins {
      myawesomecloud = {
        version = ">= 2.7.0"
        source = "azr/myawesomecloud"
      }
      happycloud = ">= 2.7.0"
    }
```

The plugin getter will look for plugins located at:
* github.com/azr/packer-plugin-myawesomecloud
* github.com/hashicorp/packer-plugin-happycloud

Packer will error if you set the `packer-plugin-` prefix in a `source`. This
will avoid conflicting with other plugins for other tools, like Terraform.

</Tab>
<Tab heading="manually">

The easiest way to manually install a plugin is to name it correctly, then place
it in the proper directory. To name a plugin correctly, make sure the binary is
named `packer-plugin-NAME`. For example, `packer-plugin-amazon` for a "plugin"
binary named "amazon". This binary will make one or more plugins available to
use. Valid types for plugins are down this page.

Once the plugin is named properly, Packer automatically discovers plugins in
the following directories in the given order. If a conflicting plugin is found
later, it will take precedence over one found earlier.

1.  The directory where `packer` is, or the executable directory.

2.  The `$HOME/.packer.d/plugins` directory, if `$HOME` is defined (unix)

3.  The `%APPDATA%/packer.d/plugins` if `%APPDATA%` is defined (windows)

4.  The `%USERPROFILE%/packer.d/plugins` if `%USERPROFILE%` is defined
    (windows)

5.  The current working directory.

6.  The directory defined in the env var `PACKER_PLUGIN_PATH`. There can be more
    than one directory defined; for example, `~/custom-dir-1:~/custom-dir-2`.
    Separate directories in the PATH string using a colon (`:`) on posix systems and
    a semicolon (`;`) on windows systems. The above example path would be able to
    find a provisioner named `packer-provisioner-foo` in either
    `~/custom-dir-1/packer-provisioner-foo` or
    `~/custom-dir-2/packer-provisioner-foo`.

The valid types for plugins are:

- `plugin` - A plugin binary that can contain one or more of each Packer plugin
  type.

- `builder` - Plugins responsible for building images for a specific
  platform.

- `post-processor` - A post-processor responsible for taking an artifact from
  a builder and turning it into something else.

- `provisioner` - A provisioner to install software on images created by a
  builder.

</Tab>
</Tabs>