--- 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 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. Depending on the template type you're using (HCL2 or legacy JSON), the methods for installing plugins may differ. If you're using HCL2, `packer init` is recommended as you can install all your requirements with one command, and those requirements are explicitly documented in the template. `packer plugins install` is also used to automate the installation from a source, and will need to be repeated for as many plugins as you need. We recommend this for JSON as the template cannot contain the information about the required plugins. Finally, you can manually install any plugin. This is mostly useful if you're in an environment with restricted internet access, or if you're installing non-final versions of plugins. Refer to the [Installation Guides](#installation-guides) section of this page for information about each, including usage examples. The remainder of this document will serve as documentation on how Packer interacts with plugins. We encourage you to read this to get familiar with this process, as it will help you troubleshoot your builds if you encounter problems with that. ## 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 Loading Workflow At initialization, Packer attempts to discover the plugins installed locally. The logic follows what's described in Configuring Packer's [plugin directory](https://developer.hashicorp.com/packer/docs/configure#packer-s-plugin-directory) section. While Packer is not verbose during this step, you can peek into what it is discovering with `PACKER_LOG=1` enabled, where you can find log lines similar to the following: ```shell [TRACE] discovering plugins in [...] [INFO] Discovered potential plugin: [...] ``` This logic however is ignored when plugins are defined in `required_plugins` blocks; instead, for every plugin required in this way, Packer will only consider them if they're installed in Packer's plugin directory, under a directory hierarchy that matches the source, with the plugin name respecting a convention. For example, if we install the `github.com/hashicorp/amazon` plugin in version 1.2.8 through either `packer init` or `packer plugins install`, this will yield the following (in a Linux x86_64 environment): ```shell └── github.com └── hashicorp └── amazon ├── packer-plugin-amazon_v1.2.8_x5.0_linux_amd64 └── packer-plugin-amazon_v1.2.8_x5.0_linux_amd64_SHA256SUM ``` Both the plugin's binary, and the related SHA256SUM file must be placed alongside each other for Packer to consider them for a `required_plugins` constraint. ## Installation Guides In order to use `packer init` for managing installation of your plugins, there are two steps required. First, 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" } } } ``` Once your template contains those `required_plugins`, run [`packer init`](/packer/docs/commands/init) 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 where the plugin is downloaded from. - 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... } ``` Plugin installation via `packer plugins install` works similar to that of the `packer init` command, but no `required_plugins` block are required, and thus can be used with both legacy JSON and HCL2 templates. ```shell packer plugins install github.com/hashicorp/vagrant ``` -> You can only install one plugin per invocation of the command. If you need to install a specific version of a plugin, you can specify a version to install as an optional argument to the command line. e.g.: `packer plugins install "github.com/hashicorp/vagrant" "v1.0.1"` 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). 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. If you have a `required_plugins` for the plugin you're manually installing, make sure it respects the constraints described in the [Plugin loading workflow](#plugin-loading-workflow) section, otherwise Packer will not be able to load it. Starting with v1.10.0 of Packer, you can also use `packer plugins install` with the `--path` flag to install a plugin from a binary, following the layout that is required to work with `required_plugins` block. ```shell packer plugins install --path github.com/hashicorp/vagrant ``` -> packer plugins install --path only works with release versions of plugins.