---
page_title: Upgrading your template to use Packer init
sidebar_title: Upgrade Your Template to use Packer init
---

# Upgrading your template to be compatible with `packer init`

The `packer init` command introduced in version v1.7.0 benefits Packer users by providing better control of plugin
usage within a Packer template configuration.

In short, `packer init` will look at the `required_plugins` block definition within a template, and download the correct
binaries for that template. For details about how the command works and where the plugins will be installed, please
refer to the [`packer init`](/docs/commands/init) documentation.

-> **Note:** `packer init` is only supported for HCL templates. You can
upgrade legacy JSON templates to HCL using the [hcl2_upgrade](/docs/commands/hcl2_upgrade) command.

## Updating your template with the `required_plugins` block

## FAQs

### Why do you need to upgrade your template?

To use the `packer init` command, you must upgrade your template to use the `required_plugins` block. The `init` command
won't work if no `required_plugins` is provided.

We strongly encourage you to upgrade and start using `required_plugins` block within your templates to manage plugin
installation, but if you prefer not to use the `required_plugins` block you can continue to
[install plugins manually](/docs/plugins#installing-plugins).


### What if you only use components that are built into the Packer core?

You don't need `packer init` for this, as of v1.7.0. But it's a good idea to get familiar with the required_plugins
block anyway, because we are going to start splitting popular HashiCorp-maintained components like the amazon-ebs
builder out of the core into their own multi-component plugins. When we do split these plugins out of the core, we will
provide a tool to help you create the correct required_plugins block.

### When should you upgrade your template?

The `packer init` command can only install plugins that have been upgraded to use the latest version of the
[Packer Plugin SDK](https://github.com/hashicorp/packer-plugin-sdk), and therefore are compatible with Packer's API
version v5.0. The plugin repository on GitHub also needs to use a specific release format. If you are not sure whether
the plugin you use fits those requirements, you can reach out to your maintainer to ask. You can also look for clues
that the plugin is ready for use with `packer init`:

* Check the plugin's CHANGELOG for notes about migrating to the packer-plugin-sdk.
* Check the name of the repository the plugin resides in. Chances are that if the repository follows the naming
  convention `packer-plugin-*` (e.g. `packer-plugin-comment`), then the plugin has been upgraded to be compatible with
  `packer init`. If the repository has a name that references a specific Packer component (for example,
  `packer-provisioner-*`, `packer-builder-*`, or `packer-post-processor-*`) then the plugin likely still needs to be
  upgraded to be compatible with `packer init`. Reach out to your plugin maintainer to request that they upgrade; the
  Packer team has written a maintainer-focused guide [here](/guides/1.7-plugin-upgrade).

If the plugin(s) have been upgraded, then they can be used with the `required_plugins` block in your upgraded template.

#### What if the plugin you need is not upgraded to API v5.0?

Since the SDK is being released at the same time as the `init` command, plugin users may face a gap between when the
Packer core v1.7.0 is released, and the plugins you use are upgraded by their maintainers. The Packer team is getting
in touch with all currently known plugin maintainers to provide support during their upgrade process.

If you are willing to upgrade your template but found out that the plugin you are using hasn't been upgraded yet,
we suggest you reach out to the plugin maintainers and ask for an upgrade; the Packer team has written a
maintainer-focused guide [here](/guides/1.7-plugin-upgrade).

Check the table below to better understand whether your plugin is compatible with `packer init`, with manual
installation, or with both for the the Packer version you are using.

| Packer Core Version | Single Component Plugin - API v4                  | Single Component Plugin - API v5.0                | Multi Component Plugin - API v5.0                        |
| ------------------- | ------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------- |
| v1.5.0 to v1.6.6    | ✋ Plugin must be manually installed              | ⛔ Plugin cannot be used with this Packer version | ⛔ Plugin cannot be used with this Packer version         |
| v1.7.0              | ⛔ Plugin cannot be used with this Packer version | ✋ Plugin must be manually installed              | 📦 Plugin can be installed manually or with `packer init` |

### How to upgrade your template

Let's use the following template as an example:

```hcl
# file: example.pkr.hcl

source "null" "basic-example" {
  communicator = "none"
}

build {
  sources = ["sources.null.basic-example"]

  provisioner "comment" {
    comment = "Hello from comment plugin"
    ui = true
    bubble_text =  true
  }
}
```

This template uses the example [packer-provisioner-comment](https://github.com/sylviamoss/packer-plugin-comment) plugin.
Until Packer v1.7.0, the binaries were installed manually.

Since the Packer v1.7.0 release, the plugin has been upgraded by its maintainers and is now called
`packer-plugin-comment`. with its latest version being v0.2.23. Knowing that, our example template can be upgraded to
use the `required_plugins` block.

```hcl
# file: example.pkr.hcl

packer {
    required_plugins {
        comment = {
            version = ">=v0.2.23"
            source = "github.com/sylviamoss/comment"
        }
    }
}

source "null" "basic-example" {
  communicator = "none"
}

build {
  sources = ["sources.null.basic-example"]

  provisioner "comment" {
    comment = "Hello from comment plugin"
    ui = true
    bubble_text =  true
  }
}
```

The upgraded template is now telling Packer that it requires a plugin named `comment` stored in a github repository
owned by the user `sylviamoss`. It also says that the template needs to use a version of the plugin equal to or greater
than `v0.2.23`. Finally, the local_name of the plugin will be `comment`, which means it will be referred to as `comment`
in the rest of the template.

Here it is a brief explanation of each field:
- `version` - Should follow the [version constraints](/docs/templates/hcl_templates/blocks/packer#version-constraints).
- `source` - Should have the GitHub hostname, the plugin's organizational namespace, and its short name. 
Packer will be responsible for determining the full GitHub
  address. For example, if the source is `github.com/sylviamoss/comment`, Packer
  will download the binaries from `github.com/sylviamoss/packer-plugin-comment`.
  To learn more about the source field, check out the [Source
  Address](/docs/plugins#source-addresses) documentation.
- `local_name`- Can be replaced with whatever you want, and the new value will become the name of the plugin.
  For example:
    ```hcl
    packer {
        required_plugins {
            bubbled_up = {
                # ...
            }
        }
    }

    # ...

    build {
        # ...

        provisioner "bubbled_up" {
            # ...
        }
    }
    ```

Once the template is upgraded, you can run `packer init example.pkr.hcl` and the output should tell you the installed
plugin, and the place where it was installed.

```shell
➜ packerdev init example.pkr.hcl
Installed plugin sylviamoss/comment v0.2.23 in "/Users/<user>/.packer.d/plugins/github.com/sylviamoss/comment/packer-plugin-comment_v0.2.23_x5.0_darwin_amd64"
```

`packer init` will only download plugin binaries and never delete existing ones. If all the required plugins are installed,
the command won't do anything unless you set the `-upgrade` flag to force download newer versions of the existing plugins.

You can uninstall a plugin by deleting it from the `.packer.d/plugins/` directory on your computer.

Now that the required comment plugin is installed via `packer init`, you can run `packer build example.pkr.hcl` as usual
and won't need to run `init` again unless you want to upgrade the plugin version.

A template with a `required_plugins` block should **always** be initialised at least once with `packer init` before
`packer build`. If the template is built before init, Packer will fail and ask for initialisation.