Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[ch5::Variables] Variable names can begin with an underscore and letters include not only the ASCII range #293

kolewu opened this issue Jul 5, 2020 · 2 comments


Copy link

kolewu commented Jul 5, 2020

It is not correct that names may only begin with a letter and that letters include only the ASCII range.

The current documentation (v2.9) is very vague on this:

Variable names should be letters, numbers, and underscores. Variables should always start with a letter.

but should is not must and the term letter is not defined (maybe it is in the code), so it's unclear from the words whether it's really [A-Za-z] like you wrote or contains also letters outside the ASCII range (that's always a problem with english speaking developers: they can't think of any letters outside ASCII).

After testing with --syntax-check Ansible understands all UTF-8 letters (tested with only some, of course) like Python does for it's names and not only [A-Za-z].

The forthcoming documentation states more clearly:

A variable name can only include letters, numbers, and underscores. Python keywords and playbook keywords are not valid variable names. A variable name cannot begin with a number.
Variable names can begin with an underscore.

I do use variable names starting with underscore to mark them as private and not redefinable (defined in the roles vars/ directory) – though the new version of the documentation clearly states, that this is not how ansible sees the variable:

In many programming languages, variables that begin with an underscore are private. This is not true in Ansible. Variables that begin with an underscore are treated exactly the same as any other variable. Do not rely on this convention for privacy or security.

So I only use this as syntactic sugar and a note to the reader: This variable is defined in the roles vars directory and cannot be changed by the user.

Copy link

geerlingguy commented Jul 21, 2020

@kolewu - Thanks for the note, and you're correct. The text in the book is currently a little inaccurate. Instead, I've updated that section of chapter 5 to the following:


Variables in Ansible work just like variables in most other systems. Variables usually begin with a letter ([A-Za-z]), but can also start with an underscore (_). Variables can include any number of letters, underscores, or numbers.

Valid variable names include foo, foo_bar, foo_bar_5, _foo, and fooBar, though the standard is to use all lowercase letters, and typically avoid numbers in variable names (no camelCase or UpperCamelCase).

Invalid variable names include foo-bar, 12, and foo bar.

In an ini-style inventory file, a variable's value is assigned using an equals sign, like so:


In a playbook or variables include file, a variable's value is assigned using a colon, like so:

foo: bar

While it's not explictly stated in Ansible's documentation, starting a variable with an underscore (e.g. _my_variable) is uncommon, but sometimes is used as a way of indicating a 'private' or 'internal use only' variable. For example, many of the geerlingguy Ansible roles I maintain prefix variables with an underscore if they're meant for internal role use only, and should not be overridden by playbooks using the role.

Copy link

This will be in the next revision of the book.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
None yet

No branches or pull requests

2 participants