Roles: directory structure and content organization

An Ansible role has a defined directory structure with seven main standard directories; you must include at least one in each role and can omit any the role does not use. By default, Ansible looks in most role directories for a main.yml file — also main.yaml and main — for relevant content. tasks/main.yml lists the tasks the role provides to the play for execution; handlers/main.yml holds handlers imported into the parent play; defaults/main.yml provides very low-precedence variable values that any other variable source overrides, while vars/main.yml provides high-precedence variables. files/ holds one or more files available to the role and its children, and templates/ holds templates, which end in .j2. meta/main.yml carries metadata including role dependencies and optional Galaxy metadata such as supported platforms — required for uploading into Galaxy as a standalone role, but not for using the role in a play. None of the files are required: a role can provide only files/ or vars/ content and still be valid, and roles can also include custom modules in library/ or plugins such as lookup_plugins/. Scope: Ansible. Reviewed October 4, 2026.