---
page_title: Local Values - HCL Configuration Language
description: >-
  Local values assign a name to an expression that can then be used multiple
  times within a folder.
---

# Local Values

`@include 'from-1.5/beta-hcl2-note.mdx'`

There are two kinds of variables in HCL Packer templates: Input variables,
sometimes simply called "variables", and Local variables, also known as
"locals". Input variables may have defaults, but those defaults can
be overridden from the command line or special variable files. Local variables
can be thought of as constants, and are not able to be overridden at runtime.

This page is about local variables. To learn about input variables, see the
[input variables](/docs/templates/hcl_templates/variables) page.

Local values assign a name to an expression, that can then be used multiple
times within a folder.

If [variables](/docs/templates/hcl_templates/variables) are analogous to function arguments then
_local values_ are comparable to a function's local variables.

Input variable and local variable usage are introduced in the [_Variables
Guide_](/guides/hcl/variables).

## Examples

Local values are defined in `local` or `locals` blocks:

```hcl
# Using the local block allows you to mark locals as sensitive, which will
# filter their values from logs.
local "mylocal" {
  expression = "${var.secret_api_key}"
  sensitive  = true
}

# Using the locals block is more compact and efficient for declaring many locals
# Ids for multiple sets of EC2 instances, merged together
locals {
  instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
}

# A computed default name prefix
locals {
  default_name_prefix = "${var.project_name}-web"
  name_prefix         = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}"
}

# Local values can be interpolated elsewhere using the "local." prefix.
source "virtualbox-iso" "example" {
  output = "${local.name_prefix}-files"
  # ...
}
```

Named local maps can be merged with local maps to implement common or default
values:

```hcl
# Define the common tags for all resources
locals {
  common_tags = {
    Component   = "awesome-app"
    Environment = "production"
  }
}

# Create a resource that blends the common tags with instance-specific tags.
source "amazon-ebs" "server" {
  source_ami    = "ami-123456"
  instance_type = "t2.micro"

  tags = "${merge(
    local.common_tags,
    map(
      "Name", "awesome-app-server",
      "Role", "server"
    )
  )}"
  # ...
}
```

## Single `local` block

The `local` block defines exactly one local variable within a folder. The block
label is the name of the local, and the "expression" is the expression that
should be evaluated to create the local. Using this block, you can optionally
supply a "sensitive" boolean to mark the variable as sensitive and filter it
from logs.

```hcl
local "mylocal" {
  expression = "${var.secret_api_key}"
  sensitive  = true
}
```

This block is also very useful for defining complex locals. Packer might take some time to expand and evaluate `locals`
with complex expressions dependent on other locals. The `locals` block is read as a map.  Maps are not sorted, and therefore
the evaluation time is not deterministic.

To avoid that, singular `local` blocks should be used instead. These will be
evaluated in the order they are defined, and the evaluation order and time will always be the same.

## `locals` block

The `locals` block defines one or more local variables within a folder.

The names given for the items in the `locals` block must be unique throughout a
folder. The given value can be any expression that is valid within the current
folder.

The expression of a local value can refer to other locals, but reference cycles
are not allowed. That is, a local cannot refer to itself or to a variable that
refers (directly or indirectly) back to it.

It's recommended to group together logically-related local values into a single
block, particularly if they depend on each other. This will help the reader
understand the relationships between variables. Conversely, prefer to define
_unrelated_ local values in _separate_ blocks, and consider annotating each
block with a comment describing any context common to all of the enclosed
locals.
