Install Plugins

This topic describes how to install external plugins for Packer. Refer toPacker Plugins Overview for additional information about plugins.

Overview

Specify one or more required plugins in a Packer template and run the initialization command. During initialization, Packer queries the source repository for plugins specified in the template that match the version constraints for the host operating system. Packer downloads and installs plugins and other dependencies specified in the template.

You can specify a remote project on GitHub for Packer to install the plugin from. Refer toRequirements for additional information about installing plugins from a remote source.

When you run the Packer template, Packer first checks the directory for installed plugins that match the version requirements specified in the template. If a suitable version of the plugin is not installed, Packer prints an error. Packer downloads the required version from thesource configuration.

Manual installation method

You can manually install plugins if you are unable to specify plugins in an HCL template file. You may need to use the manual plugin installation method if the plugin source is a non-GitHub project or if your plugins are still in development.

Manually install a plugin using thepacker plugins install command. You specify a local or remote plugin source and include a path to the binary to generate the SHA256SUM file required to load the plugin during Packer builds. Refer toRequirements for additional information about installing plugins from a remote source.

Note that Packer checks the plugin installation directory against therequired_plugins block in the Packer template when you build artifacts using the template. Plugins specified in the template that have been installed manually must still comply with the version constraints set in the template.

Installation directory

By default, Packer installs plugins into the plugins directory at$HOME/.config/packer/plugins on Unix and%APPDATA%\packer.d\plugins on Windows, but you can specify a different directory using thePACKER_PLUGIN_PATH environment variable.

Requirements

To install a plugin from a remote source, the plugin must meet the following requirements:

• The plugin project must be hosted on GitHub.
• The repository must be namedpacker-plugin-<name>.
• The project must have semantic version tags per the following format:v<major>.<minor>.<patch>.
• The release linked to the tag must be available with ashasums file that indicates which files are available in the release.

GitHub API token

GitHub's public API limits the number of unauthenticated requests per hour from a single IP address. Refer to theGitHub rate limits documentation for additional information.

If you expect to exceed the request rate limit, you can use a GitHub API token to authenticate requests and exceed the rate limit. We recommend setting a GitHub API token when running Packer from a continuous integration server to avoid potential rate limiting errors. Refer toAuthenticate requests to the GitHub API for instructions.

Install a plugin

1. In your Packer template file, add therequired_plugins block to thepacker block.

2. Specify the name of the plugin and itsversion andsource parameters. Setting a correctversion constraint string is important forpinning plugin versions for build reproducibility. Refer to thepacker block configuration reference for additional information.

   The following example configures Packer to install a plugin calledhappycloud. When the template is initialized, Packer downloads version 2.7.0 or newer of the plugin from GitHub:

   ```hclpacker {  required_plugins {    happycloud = {      version = ">= 2.7.0"      source = "github.com/hashicorp/happycloud"    }  }} ```

3. Run thepacker init command. Packer lists all installed plugins then installs the latest plugin version matching the version constraints specified in therequired_plugins block. Refer to theinit command reference for additional information.

Install HashiCorp-maintained plugins

HashiCorp now makes the following official HashiCorp-maintained plugins available through theHashiCorp release site.

These plugins include:

• Amazon
• Ansible
• Azure
• Docker
• Google Cloud Platform
• QEMU
• Vagrant
• VirtualBox

Starting in Packer 1.14.0, Packer automatically installs these plugins from the new release source, and you do not need to make any changes to your Packer templates. To continue to automatically receive updates to these plugins, you must upgrade to Packer 1.14.0 or newer. If you cannot upgrade your version of Packer, you can still install new versions of these plugins manually. Refer toManually install plugins using the CLI for more information.

Manually install plugins using the CLI

You can use thepacker plugins install command to manually install plugin binaries.Use the--path flag to specify a local source. Packer then automatically calculates the SHA256SUM file and installs the files into the Packer plugin directory:

$ packer plugins install --path<path-to-downloaded-extracted-binary> <hostname>/<namespace>/<plugin-name>

The following example installs thehappycloud plugin from a locally-sourced binary:

$ unzip packer-plugin-happycloud.zip$ ls -l-rwxr-xr-x [...] happycloud$ packer plugins install --path happycloud github.com/hashicorp/happycloud

Refer to thepacker plugins install reference for additional information.

Upgrade plugins

To upgrade plugins that are already installed, run thepacker init with the--upgrade flag. Packer retrieves the latest versions of installed plugins specified in the template configuration.

The following example upgrades plugins according to the template in the current directory:

$ packer init --upgrade.

Refer topacker init command for additional information.

Use a plugin under development

If a development binary, such as a manually-built binary, is available at the specified source, Packer uses it in the build if it is the highest compatible version installed and if no final plugin version with the same version number is installed alongside it.

In the following example, version1.1.0 or newer is required:

packer= {    required_plugins= {        amazon= {            source= "github.com/hashicorp/amazon"            version= ">= 1.1.0"        }    }. . .}

Packer uses the-dev version of the Amazon plugin if the following binaries are available:

/Users/dev/.packer.d/plugins└─ github.com   └─ hashicorp        └── amazon          ├── packer-plugin-amazon_v1.1.0_x5.0_darwin_arm64          ├── packer-plugin-amazon_v1.1.0_x5.0_darwin_arm64_SHA256SUM          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64          └── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64_SHA256SUM

When a non-development version of 1.1.1 becomes available, the binary takes precedence over the development binary:

/Users/dev/.packer.d/plugins└─ github.com   └─ hashicorp        └── amazon          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64          ├── packer-plugin-amazon_v1.1.1-dev_x5.0_darwin_arm64_SHA256SUM          ├── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64          └── packer-plugin-amazon_v1.1.1_x5.0_darwin_arm64_SHA256SUM

Example Docker plugin

Complete the following steps to build and install a custom version of the Docker plugin as an example:

1. Clone the plugin's GitHub repository.

   $ git clone https://github.com/hashicorp/packer-plugin-docker.git

2. Change to the plugin directory root and run thego build command to build the plugin as a development binary.

   $ cd packer-plugin-docker$ go build -ldflags="-X github.com/hashicorp/packer-plugin-docker/version.VersionPrerelease=dev" -o packer-plugin-docker-dev

3. Validate the release version.

   $ ./packer-plugin-docker-dev describe{"version":"1.0.10-dev","sdk_version":"0.5.2","api_version":"x5.0","builders":["-packer-default-plugin-name-"],"post_processors":["import","push","save","tag"],"provisioners":[],"datasources":[]}

4. Use thepacker plugins install command to install the development binary.

   packer plugins install --path packer-plugin-docker-dev github.com/hashicorp/dockerSuccessfully installed plugin github.com/hashicorp/docker from $HOME/Development/packer-plugin-docker/packer-plugin-docker-dev to ~/github.com/hashicorp/docker/packer-plugin-docker_v1.0.10-dev_x5.0_darwin_arm64

5. Run apacker build with the newly installed plugin.

   $ packer build.

For convenience, the makefile in the Packer plugin scaffolding repository builds and installs development binaries usingmake dev.

Refer to the documentation in thePacker plugin scaffolding repository for additional information.

Authenticate requests to the GitHub API

You can set thePACKER_GITHUB_API_TOKEN environment variable to send more requests per hour than the limits imposed by the GitHub API:

1. Go to your personalaccess token page togenerate a new token.

2. Set thePACKER_GITHUB_API_TOKEN environment variable to your token value:

   $ export PACKER_GITHUB_API_TOKEN=<token>