Ansible ansible.builtin vs ansible.legacy: Collection Namespaces Explained
By Luca Berton · Published 2024-01-01 · Category: installation
Understand ansible.builtin vs ansible.legacy namespaces. Learn when to use FQCN, how module resolution works, and migrate to fully qualified collection names.
What is the "ansible.builtin" Ansible collection? What is the "ansible.legacy" collection? Today we're going to talk about Ansible's most essential modules and plugins and how we can use them in our everyday Playbook. I'm Luca Berton, Ansible Automation Expert, and welcome to today's lesson.
What is ansible.builtin collection? The "ansible.builtin" collection refers to modules & plugins shipped with ansible-core. Technically is a synthetic collection, virtually constructed by the core engine.
What is ansible.legacy collection? The "ansible.legacy" collection is a superset of "ansible.builtin" with 'custom' plugins in the configured paths and adjacent directories. We use the "ansible.legacy" when we don't specify any Ansible collection in our playbook. Technically is a synthetic collection, virtually constructed by the core engine.
Links • https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#what-is-the-difference-between-ansible-legacy-and-ansible-builtin-collections • https://docs.ansible.com/ansible/latest/reference_appendices/config.html#default-action-plugin-path
Demo Live Playbook about "ansible.builtin" vs. "ansible.legacy" collections. Let's jump in a quick Playbook to demonstrate the difference between the "ansible.builtin" vs. "ansible.legacy" collections. I'm going to create a custom "debug" module that prints the extra text "foo" when used with the "msg" parameter. Let's see the different results when we execute with "ansible.builtin", "ansible.legacy" or without specifying any collections. The code is the following.
common code • inventory (localhost) • ansible.cfg • plugins/action/debug.py
ansible.builtin code • ansible.builtin.yml
ansible.builtin execution
ansible.legacy code • ansible.legacy.yml
ansible.legacy execution
ansible.vanilla code • ansible.vanilla.yml
ansible.legacy execution
Conclusion
Now you know more about the "ansible.builtin" and the "ansible.legacy" collections. This is a great foundation for your Ansible Playbook onward.
Quick Comparison
What's the Difference?
| Namespace | Resolution | When Used | |-----------|-----------|-----------| | ansible.builtin | Only built-in modules | Explicit, recommended | | ansible.legacy | Built-in + custom in configured paths | Backward compatibility | | Short name (copy) | Legacy resolution order | Pre-2.10 style |
Why Use FQCN?
Resolution Order
When you use a short name like copy: Check ansible.legacy namespace (custom module paths) Fall back to ansible.builtin
When you use ansible.builtin.copy: Only checks built-in modules — deterministic
Migrate to FQCN
Before (Legacy)
After (FQCN)
Common Built-in Modules
Collection Modules (Not Built-in)
ansible-lint FQCN Rules
FAQ
Do I have to use FQCN?
No — short names still work. But FQCN is recommended for clarity and to avoid conflicts with custom modules sharing the same name.
Is ansible.legacy deprecated?
No — ansible.legacy exists for backward compatibility. It's not deprecated but using ansible.builtin explicitly is better practice.
What about action plugins?
Same rules apply — ansible.builtin.include_role, ansible.builtin.import_tasks, etc. FQCN works for all plugin types.
Quick Comparison
| Namespace | What It Contains | Example | |-----------|-----------------|---------| | ansible.builtin | Core modules shipped with ansible-core | ansible.builtin.copy | | ansible.legacy | Fallback namespace for unqualified names | ansible.legacy.copy |
FQCN (Fully Qualified Collection Name)
How Resolution Works
When you write copy: (without namespace): Ansible checks ansible.builtin.copy If not found, checks ansible.legacy.copy ansible.legacy checks library/ dirs and collections in order
ansible-lint fqcn Rule
Collection Modules
When ansible.legacy Matters
Migration to FQCN
FAQ
Do I MUST use FQCN?
Not technically — short names still work. But FQCN is best practice: it's explicit, avoids name collisions between collections, and satisfies ansible-lint.
What if two collections have the same module name?
FQCN prevents ambiguity. Without it, resolution depends on collection loading order — fragile and unpredictable.
Will short names be removed?
No — ansible.legacy fallback is maintained for backward compatibility. But new code should always use FQCN.
Related Articles • Ansible Template Guide • Ansible Inventory Guide
Category: installation
Watch the video: Ansible ansible.builtin vs ansible.legacy: Collection Namespaces Explained — Video Tutorial