AnsiblePilot — Master Ansible Automation

AnsiblePilot is the leading resource for learning Ansible automation, DevOps, and infrastructure as code. Browse over 1,400 tutorials covering Ansible modules, playbooks, roles, collections, and real-world examples. Whether you are a beginner or an experienced engineer, our step-by-step guides help you automate Linux, Windows, cloud, containers, and network infrastructure.

Popular Topics

About Luca Berton

Luca Berton is an Ansible automation expert, author of 8 Ansible books published by Apress and Leanpub including "Ansible for VMware by Examples" and "Ansible for Kubernetes by Example", and creator of the Ansible Pilot YouTube channel. He shares practical automation knowledge through tutorials, books, and video courses to help IT professionals and DevOps engineers master infrastructure automation.

Ansible Galaxy: Install Collections & Roles — Complete Guide (2026)

By Luca Berton · Published 2024-01-01 · Category: installation

Complete guide to Ansible Galaxy. Install collections and roles with ansible-galaxy, manage requirements.yml, create custom roles, publish to Galaxy Hub.

Ansible Galaxy: Install Collections & Roles — Complete Guide (2026)

Ansible Galaxy is the hub for finding, sharing, and downloading Ansible content. This guide covers everything from installing collections and roles to creating and publishing your own.

See also: Ansible Galaxy: Install, Create & Share Roles and Collections (Guide)

What is Ansible Galaxy?

Ansible Galaxy serves two purposes:

  1. Galaxy Hub () — a public repository of community-contributed collections and roles
  2. ansible-galaxy CLI — the command-line tool to install, create, and manage collections and roles

Installing Collections

Install from Galaxy Hub

# Install a specific 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.docker -p ./collections

Install from requirements.yml

Create a requirements.yml file:

---
collections:
  - name: community.general
    version: ">=9.0.0"
  - name: ansible.posix
  - name: community.postgresql
    version: "4.0.0"
  - name: amazon.aws
  - name: community.docker
  - name: ansible.windows

Install all at once:

ansible-galaxy collection install -r requirements.yml

Install from Git Repository

# Install from GitHub
ansible-galaxy collection install git+https://github.com/ansible-collections/community.general.git

# Install specific branch/tag
ansible-galaxy collection install git+https://github.com/org/collection.git,main

Install from Tarball

# Download and install local tarball
ansible-galaxy collection install ./community-general-9.0.0.tar.gz

Installing Roles

Install from Galaxy Hub

# Install a role
ansible-galaxy role install geerlingguy.docker

# Install specific version
ansible-galaxy role install geerlingguy.docker,7.0.0

# Install to custom path
ansible-galaxy role install geerlingguy.docker -p ./roles

Install from requirements.yml

---
roles:
  - name: geerlingguy.docker
    version: "7.0.0"
  - name: geerlingguy.nginx
  - name: geerlingguy.postgresql
  - src: https://github.com/username/my-role.git
    name: my-role
    version: main
ansible-galaxy role install -r requirements.yml

See also: Ansible Creator CLI: Scaffold Collections, Roles & Projects (v26.4.0)

Managing Installed Content

List Installed Collections

ansible-galaxy collection list

# Show specific collection info
ansible-galaxy collection list community.general

List Installed Roles

ansible-galaxy role list

Upgrade Collections

# Upgrade a specific collection
ansible-galaxy collection install community.general --upgrade

# Upgrade all from requirements
ansible-galaxy collection install -r requirements.yml --upgrade

Remove Collections

# Remove a collection (manual — delete the directory)
rm -rf ~/.ansible/collections/ansible_collections/community/general/

Collection Installation Paths

Default locations (in priority order):

./collections/ansible_collections/     # Project-local
~/.ansible/collections/ansible_collections/  # User-level
/usr/share/ansible/collections/ansible_collections/  # System-wide

Configure in ansible.cfg:

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

See also: Ansible Galaxy Collections: Install, Use & requirements.yml Guide

Creating a Custom Role

# Scaffold a new role
ansible-galaxy role init my_nginx_role

# This creates:
# my_nginx_role/
# ├── defaults/main.yml
# ├── files/
# ├── handlers/main.yml
# ├── meta/main.yml
# ├── README.md
# ├── tasks/main.yml
# ├── templates/
# ├── tests/
# └── vars/main.yml

Creating a Custom Collection

# Scaffold a new collection
ansible-galaxy collection init my_namespace.my_collection

# This creates:
# my_namespace/my_collection/
# ├── docs/
# ├── galaxy.yml
# ├── plugins/
# │   └── README.md
# ├── README.md
# └── roles/

Build and Publish

# Build the collection
cd my_namespace/my_collection
ansible-galaxy collection build

# Publish to Galaxy Hub
ansible-galaxy collection publish ./my_namespace-my_collection-1.0.0.tar.gz --api-key=YOUR_TOKEN

Private Galaxy Server (Automation Hub)

For enterprise environments, use a private Galaxy server:

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy

[galaxy_server.automation_hub]
url = https://hub.example.com/api/galaxy/
token = your-private-token

[galaxy_server.galaxy]
url = https://galaxy.ansible.com/
# Install from private server
ansible-galaxy collection install my_company.internal_tools -s automation_hub
CollectionUse Case
community.generalGeneral-purpose modules (1,200+)
ansible.posixPOSIX systems (mount, sysctl, at)
community.postgresqlPostgreSQL management
amazon.awsAWS cloud automation
azure.azcollectionAzure cloud automation
community.dockerDocker container management
ansible.windowsWindows automation
community.vmwareVMware vSphere automation
kubernetes.coreKubernetes management
ansible.netcommonNetwork automation

FAQ

What is the difference between Ansible collections and roles?

Collections are the modern packaging format that can contain roles, modules, plugins, and playbooks. Roles are simpler — they package tasks, handlers, variables, and templates for a specific function. Collections supersede standalone roles as the primary distribution format.

Where does ansible-galaxy install collections?

By default, ~/.ansible/collections/ansible_collections/. Override with -p ./collections flag or collections_path in ansible.cfg. Project-local collections take priority over user and system paths.

How do I use a Galaxy role in a playbook?

Reference the role name in your playbook's roles section: roles: [geerlingguy.docker]. Or use include_role/import_role in tasks. Install the role first with ansible-galaxy role install.

Do I need an account to download from Ansible Galaxy?

No. Downloading and installing collections and roles from Galaxy Hub is free and doesn't require authentication. You only need an account to publish content.

How do I install collections in an air-gapped environment?

Download collection tarballs on a connected machine with ansible-galaxy collection download, then transfer to the air-gapped system and install with ansible-galaxy collection install ./tarball.tar.gz.

Conclusion

Ansible Galaxy is essential for leveraging community automation content. Use requirements.yml to manage your project dependencies, install collections for module access, and consider creating your own collections for reusable automation.

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home