---
description: |
  The `packer hcl2_upgrade` Packer command transpiles a JSON
  configuration template into HCL2 so you can transition to HCL templates.
page_title: packer hcl2_upgrade command reference
---

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
> [!IMPORTANT]  
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

# `packer hcl2_upgrade` command reference

The `packer hcl2_upgrade` Packer command transpiles a JSON
configuration template to it's formatted HCL2 counterpart. The command
returns a zero exit status on success and a non-zero exit status on failure.

-> **This command is beta**. We do not recommend using beta functionality in production environments. To report an issue and provide feedback, [open a GitHub
issue](https://github.com/hashicorp/packer/issues/new/choose).

## Usage

```shell-session
$ packer hcl2_upgrade my-template.json

Successfully created my-template.json.pkr.hcl
```

## Upgrading variables file

From **v1.7.1**, the `hcl2_upgrade` command can upgrade a variables file.

<Tabs>
<Tab heading="Original file (variables.json)">

```json
{
  "variables": {
    "aws_region": null,
    "aws_secondary_region": "{{ env `AWS_DEFAULT_REGION` }}",
    "aws_secret_key": "",
    "aws_access_key": ""
  },
  "sensitive-variables": ["aws_secret_key", "aws_access_key"]
}
```

</Tab>
<Tab heading="Result file (variables.pkr.hcl)">

```hcl
variable "aws_access_key" {
  type      = string
  default   = ""
  sensitive = true
}

variable "aws_region" {
  type = string
}

variable "aws_secondary_region" {
  type    = string
  default = "${env("AWS_DEFAULT_REGION")}"
}

variable "aws_secret_key" {
  type      = string
  default   = ""
  sensitive = true
}
```

</Tab>
</Tabs>

## Go template functions

`hcl2_upgrade` will do its best to transform your Go _template calls_ to HCL2,
here is the list of calls that should get transformed:

- `` {{ user `my_var` }} `` becomes `${var.my_var}`.
- `` {{ env `my_var` }} `` becomes `${var.my_var}`. Packer HCL2 supports
  environment variables through input variables. See
  [docs](/packer/docs/templates/hcl_templates/variables#environment-variables)
  for more info.
- `{{ timestamp }}` becomes `${local.timestamp}`, the local variable
  will be created for all generated files.
- `` {{ build `ID` }} `` becomes `${build.ID}`.

The rest of the calls should remain Go template calls for now, this will be
improved over time.

-> **Note**: The `hcl2_upgrade` command does its best to transform template
calls to their JSON counterpart, but it might fail. In that case the
`hcl2_upgrade` command will simply output the local HCL2 block without
transformation and with the error message in a comment. We are currently
working on improving this part of the transformer.

## Options

- `-output-file` - Filename of the hcl2 generated template. Defaults to
  JSON_TEMPLATE.pkr.hcl; for example, if the file is called
  "packerparty.json", the default output-file is "packerparty.json.pkr.hcl".
- `-with-annotations` - Adds helpful comments to the HCL template with
  information about the generated HCL2 blocks.

## User variables using other user variables

Packer JSON recently started allowing using user variables from variables. In
HCL2, input variables cannot use functions nor other variables and are
virtually static, local variables must be used instead to craft more dynamic
variables.

For v1.7.0 and lower, `hcl2_upgrade` doesn't upgrade variables to local variables,
and it is up to you to upgrade them manually. Upgrade to **v1.7.1** to let the command do it
automatically for you.

Here is an example of a local variable using a string input variables:

```hcl
variable "foo" {
  default = "Hello,"
}

variable "bar" {
  default = "World!"
}

locals {
  baz = "${var.foo} ${var.bar}"
}
```

## Upgrading templates that use third-party community plugins

If your template references a plugin that is not bundled with the main Packer
binary, you need to make sure that the [plugin is installed](/packer/docs/plugins#installing-plugins)
or you will get an `unknown builder type` error. Packer needs to load the plugin
to transpose the template.
