--- 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 Choose the tab that corresponds to the type of plugin you want to install. If you are not sure, check the plugin's name. - Multi-component plugin names have the prefix `packer-plugin-`. - Single-component plugin names have a prefix containing the component type, like `packer-provisioner-` or `packer-builder`. -> **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:** 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. ## Implicit Github urls Using the following example : ```hcl required_plugins { happycloud = { version = ">= 2.7.0" source = "github.com/azr/happycloud" } } ``` The plugin getter will look for plugins located at: - github.com/azr/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. -> 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 ``` ## Plugin Installation Workflow 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. * [`packer plugins install`](/packer/docs/commands/plugins) will install plugins in the **last** directory in the following numbered list. 1. `PACKER_PLUGINS_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. For manual installation of plugin binaries, without the `packer plugins` command, please continue reading. 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 components available to use. Valid types for plugins are down this page. The valid types for plugins are: - `plugin` - A plugin binary that can contain one or more of each Packer component 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. 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-COMPONENT-NAME`. For example, `packer-provisioner-comment` for a "plugin" binary named "comment". This binary will make a single provisioner named `comment` available to use. Valid types for plugins are down this page. The valid types for plugins are: - `plugin` - A plugin binary that can contain one or more of each Packer component 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.