Docs / Language: Variables

Language: Variables

This is the latest version of Puppet. Puppet Enterprise 2015.2 users should see the Puppet 4.2 docs and the PE 2015.2 docs. PE 3.8 users should see the Puppet 3.8 docs and the PE 3.8 docs.

Variables store values so they can be accessed later.

In the Puppet language, variables are actually constants, since they can’t be reassigned. But since “variable” is more comfortable and familiar to most people, the name has stuck.

Facts and Built-In Variables

Puppet has many built-in variables that you can use in your manifests. For a list of these, see the page on facts and built-in variables.



$content = "some content\n"

Variable names are prefixed with a $ (dollar sign). Values are assigned to them with the = (equal sign) assignment operator.

Variables can be assigned values of any data type. Any statement that resolves to a normal value (including expressions, functions, and other variables) can be used in place of a literal value. The variable will contain the value that the statement resolves to, rather than a reference to the statement.

Variables can only be assigned using their short name. That is, a given scope cannot assign values to variables in a foreign scope.

Assigning Multiple Variables

You can assign multiple vairiables at once from an array or hash.


When assigning multiple variables from an array, there must be an equal number of variables and values. Nested arrays can also be used.

    [$a, $b, $c] = [1,2,3]      # $a = 1, $b = 2, $c = 3
    [$a, [$b, $c]] = [1,[2,3]]  # $a = 1, $b = 2, $c = 3
    [$a, $b] = [1, [2]]         # $a = 1, $b = [2]
    [$a, [$b]] = [1, [2]]       # $a = 1, $b = 2

If the number of variables and values do not match, the operation will fail.


When you assign multiple variables with a hash, the variables are listed in an array on the left side of the assignment operator, and the hash is on the right. Hash keys must match their corresponding variable name.

    [$a, $b] = {a => 10, b => 20}           # $a = 10, $b = 20

There can be extra key/value pairs in the hash, but all variables to the left of the operator must have a corresponding key in the hash.

    [$a, $c] = {a => 5, b => 10, c => 15, d => 22}   # $a = 5, $c = 15


file {'/tmp/testing':
  ensure  => file,
  content => $content,

$address_array = [$address1, $address2, $address3]

The name of a variable can be used in any place where a value of its data type would be accepted, including expressions, functions, and resource attributes. Puppet will replace the name of the variable with its value.

By default, unassigned variables have a value of undef; see Unassigned Variables and Strict Mode below for more details.


$rule = "Allow * from $ipaddress"
file { "${homedir}/.vim":
  ensure => directory,

Puppet can resolve variables in double-quoted strings; this is called “interpolation.”

Inside a double-quoted string, you can optionally surround the name of the variable (the portion after the $) with curly braces (${var_name}). This syntax helps to avoid ambiguity and allows variables to be placed directly next to non-whitespace characters. These optional curly braces are only allowed inside strings.



The area of code where a given variable is visible is dictated by its scope. Variables in a given scope are only available within that scope and its child scopes, and any local scope can locally override the variables it receives from its parents.

See the section on scope for complete details.

Accessing Out-of-Scope Variables

You can access out-of-scope variables from named scopes by using their qualified names:

$vhostdir = $apache::params::vhostdir

Note that the top scope’s name is the empty string — thus, the qualified name of a top scope variable would be, e.g., $::osfamily. See scope for details.

Unassigned Variables and Strict Mode

By default, you can access variables that have never had values assigned to them. If you do, their value will be undef.

This is usually not what you want, because using an unassigned variable is often an accident or a typo.

If you’d rather have unassigned variable usage throw an error, so you can get warned early and fix the problem, you can enable strict mode. Set strict_variables = true in puppet.conf on your Puppet master(s) and any nodes that run Puppet apply.

No Reassignment

Unlike most other languages, Puppet only allows a given variable to be assigned once within a given scope. You may not change the value of a variable, although you may assign a different value to the same variable name in a new scope:

# scope-example.pp
# Run with puppet apply --certname scope-example.pp
$myvar = "Top scope value"
node '' {
  $myvar = "Node scope value"
  notice( "from www1: $myvar" )
  include myclass
node '' {
  notice( "from db1: $myvar" )
  include myclass
class myclass {
  $myvar = "Local scope value"
  notice( "from myclass: $myvar" )

In the example above, $myvar has several different values, but only one value will apply to any given scope.

Evaluation-Order Dependence

Unlike resource declarations, variable assignments are evaluation-order dependent. This means you cannot resolve a variable before it has been assigned.

This is the main way in which the Puppet language fails to be fully declarative.


Variable names begin with a $ (dollar sign) and are case-sensitive.

Most variable names must start with a lowercase letter or an underscore. The exception is regex capture variables, which are named with only numbers.

Variable names can include:

  • Uppercase and lowercase letters
  • Numbers
  • Underscores (_)

If the first character is an underscore, that variable should only be accessed from its own local scope; using qualified variable names where any namespace segment begins with _ is deprecated.

Note that some variable names are reserved.

Qualified Variable Names

Qualified variable names are prefixed with the name of their scope and the :: (double colon) namespace separator. (For example, the $vhostdir variable from the apache::params class would be $apache::params::vhostdir.)

Optionally, the name of the very first namespace may be empty, representing the top namespace. In previous versions of the Puppet language, this was often used to work around bugs, but it’s not necessary in this version. The main use is to indicate to readers that you’re accessing a top-scope variable, e.g. $::is_virtual.

Regular Expressions For Variable Names

Short variable names should match the following regular expression:


Qualified variable names should match the following regular expression:


↑ Back to top