Ansible Collections: What They Are & How to Use Them (2026 Guide)

Ansible Collections are the standard way to package and distribute Ansible content — modules, roles, plugins, and playbooks — as a single installable unit. Since Ansible 2.10, most modules have moved from the monolithic ansible package into separate collections. Understanding collections is essential for modern Ansible automation.

What Are Ansible Collections?

A collection is a distribution format that bundles: • Modules (e.g., amazon.aws.ec2_instance) • Roles (reusable task sets) • Plugins (filters, callbacks, inventory, connection) • Playbooks (example or utility playbooks) • Documentation

Collections use a namespace format: namespace.collection_name (e.g., community.general, amazon.aws, cisco.ios).

See also: Ansible Galaxy: Install Collections & Roles from Galaxy Hub (Guide)

Install Collections

From Ansible Galaxy

# Install a single collection
ansible-galaxy collection install community.general
# Install a specific version
ansible-galaxy collection install community.general:9.0.0
# Install to a custom path
ansible-galaxy collection install community.general -p ./collections
# Force reinstall
ansible-galaxy collection install community.general --force

From requirements.yml

Create requirements.yml for reproducible installs:

---
collections:
  - name: community.general
    version: ">=9.0.0"
  - name: amazon.aws
    version: "8.0.0"
  - name: ansible.posix
  - name: community.docker
    version: ">=3.0.0,<4.0.0"
# From a Git repository
  - name: https://github.com/myorg/my_collection.git
    type: git
    version: main
# From a tarball URL
  - name: https://example.com/my_collection-1.0.0.tar.gz
    type: url

Install all:

ansible-galaxy collection install -r requirements.yml
ansible-galaxy collection install -r requirements.yml --force-with-deps

From Automation Hub (Red Hat)

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy
[galaxy_server.automation_hub]
url=https://console.redhat.com/api/automation-hub/content/published/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=your-token-here
[galaxy_server.galaxy]
url=https://galaxy.ansible.com/

ansible-galaxy collection install redhat.rhel_system_roles

Use Collections in Playbooks

Fully Qualified Collection Name (FQCN)

The recommended approach — explicit and unambiguous:

- name: Use FQCN for all modules
  hosts: all
  tasks:
    - name: Install package
      ansible.builtin.package:
        name: nginx
        state: present
- name: Manage firewall
      ansible.posix.firewalld:
        port: 80/tcp
        permanent: true
        state: enabled
- name: Create EC2 instance
      amazon.aws.ec2_instance:
        name: webserver
        instance_type: t3.micro
        image_id: ami-12345678

collections Keyword (Shorthand)

- name: Use collections keyword
  hosts: all
  collections:
    - community.general
    - ansible.posix
  tasks:
    - name: Manage timezone (no FQCN needed)
      timezone:
        name: Europe/London
- name: Set sysctl value
      sysctl:
        name: net.ipv4.ip_forward
        value: '1'

> Best Practice: Always use FQCNs. The collections keyword is convenient but can cause confusion when multiple collections provide modules with the same name.

See also: Ansible Role Input Validation with validate_argument_spec

List Installed Collections

# List all installed collections
ansible-galaxy collection list
# List specific collection
ansible-galaxy collection list community.general
# Show detailed info
ansible-galaxy collection list --format yaml
# List collections in a specific path
ansible-galaxy collection list -p ./collections

Collection Search Paths

Ansible looks for collections in these paths (in order): ./collections/ansible_collections/ ~/.ansible/collections/ansible_collections/ /usr/share/ansible/collections/ansible_collections/

Configure in ansible.cfg:

[defaults]
collections_path = ./collections:~/.ansible/collections:/usr/share/ansible/collections

Or with environment variable:

export ANSIBLE_COLLECTIONS_PATH=./collections:~/.ansible/collections

See also: Ansible Automation: Complete Guide to IT Automation with Playbook Examples

Popular Collections

| Collection | Content | Use Case | |-----------|---------|----------| | ansible.builtin | Core modules, plugins | Included with ansible-core | | community.general | 800+ modules | General-purpose automation | | ansible.posix | POSIX system modules | Linux/UNIX management | | amazon.aws | AWS modules | Cloud automation | | azure.azcollection | Azure modules | Cloud automation | | google.cloud | GCP modules | Cloud automation | | community.docker | Docker modules | Container management | | kubernetes.core | K8s modules | Container orchestration | | cisco.ios / cisco.nxos | Network modules | Network automation | | community.vmware | VMware modules | Virtualization | | community.postgresql | PostgreSQL modules | Database management | | redhat.rhel_system_roles | RHEL system roles | RHEL management |

Create a Custom Collection

Initialize Structure

ansible-galaxy collection init myorg.myapp

Creates:

myorg/myapp/
├── docs/
├── galaxy.yml          # Collection metadata
├── meta/
│   └── runtime.yml     # Runtime configuration
├── plugins/
│   ├── modules/        # Custom modules
│   ├── module_utils/   # Shared module code
│   ├── filter/         # Custom filter plugins
│   └── inventory/      # Custom inventory plugins
├── roles/              # Bundled roles
├── playbooks/          # Example playbooks
├── tests/
└── README.md

galaxy.yml Metadata

namespace: myorg
name: myapp
version: 1.0.0
readme: README.md
authors:
  - Your Name <you@example.com>
description: My custom collection for app automation
license:
  - GPL-3.0-or-later
tags:
  - automation
  - deployment
dependencies:
  ansible.posix: ">=1.5.0"
  community.general: ">=8.0.0"
repository: https://github.com/myorg/ansible-collection-myapp

Add a Custom Module

# plugins/modules/deploy_app.py
DOCUMENTATION = r'''
module: deploy_app
short_description: Deploy application
description:
  - Deploy and configure application on target hosts
options:
  version:
    description: Application version to deploy
    required: true
    type: str
  config_path:
    description: Path to configuration file
    type: str
    default: /etc/myapp/config.yml
'''
from ansible.module_utils.basic import AnsibleModule
def main():
    module = AnsibleModule(
        argument_spec=dict(
            version=dict(required=True, type='str'),
            config_path=dict(type='str', default='/etc/myapp/config.yml'),
        ),
    )
    # Module logic here
    module.exit_json(changed=True, msg=f"Deployed version {module.params['version']}")
if __name__ == '__main__':
    main()

Add a Custom Filter Plugin

# plugins/filter/myfilters.py
class FilterModule:
    def filters(self):
        return {
            'normalize_hostname': self.normalize_hostname,
        }
def normalize_hostname(self, hostname):
        return hostname.lower().replace(' ', '-').replace('_', '-')

Use it:

msg: "{{ 'My_Web Server' | myorg.myapp.normalize_hostname }}"
# Output: "my-web-server"

Build and Publish

# Build the collection tarball
ansible-galaxy collection build
# Publish to Galaxy
ansible-galaxy collection publish myorg-myapp-1.0.0.tar.gz --api-key=your-key
# Install from local tarball
ansible-galaxy collection install myorg-myapp-1.0.0.tar.gz

Collection Dependencies in Roles

# roles/webserver/meta/main.yml
collections:
  - ansible.posix
  - community.general
dependencies: []

Execution Environments (EE)

For containerized Ansible execution with pinned collections:

# execution-environment.yml
version: 3
dependencies:
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt
images:
  base_image:
    name: quay.io/ansible/ansible-runner:latest

ansible-builder build -t my-ee:latest

FAQ

What are Ansible Collections?

Collections are the standard packaging format for distributing Ansible content (modules, roles, plugins, playbooks). They replaced the monolithic Ansible package starting with version 2.10, allowing independent versioning and distribution of automation content.

What is FQCN in Ansible?

FQCN (Fully Qualified Collection Name) is the complete module reference format: namespace.collection.module_name. For example, ansible.builtin.copy or amazon.aws.ec2_instance. FQCNs prevent naming conflicts and make it clear which collection provides each module.

How do I install Ansible collections?

Use ansible-galaxy collection install collection_name for individual installs, or create a requirements.yml file and run ansible-galaxy collection install -r requirements.yml for reproducible multi-collection installs.

Where are Ansible collections installed?

By default, collections install to ~/.ansible/collections/ansible_collections/. Override with -p path flag, collections_path in ansible.cfg, or the ANSIBLE_COLLECTIONS_PATH environment variable.

How do I create a custom Ansible collection?

Run ansible-galaxy collection init namespace.name to create the directory structure, add modules/roles/plugins, fill in galaxy.yml metadata, build with ansible-galaxy collection build, and publish with ansible-galaxy collection publish.

Conclusion

Ansible Collections are the modern way to organize, distribute, and consume automation content: • Install with ansible-galaxy collection install • Use FQCNs for explicit, conflict-free module references • Pin versions in requirements.yml for reproducibility • Create custom collections to package your organization's automation

Every modern Ansible project should use collections and FQCNs for maintainable, portable automation.

Related Articles

• Ansible Galaxy Complete Guide • Ansible Roles: Create Reusable Automation • Ansible Configuration: ansible.cfg Complete Guide • How to Install Ansible with pip