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

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: Galaxy Hub () — a public repository of community-contributed collections and roles 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

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

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

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/

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

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

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

Popular Collections

| Collection | Use Case | |-----------|----------| | community.general | General-purpose modules (1,200+) | | ansible.posix | POSIX systems (mount, sysctl, at) | | community.postgresql | PostgreSQL management | | amazon.aws | AWS cloud automation | | azure.azcollection | Azure cloud automation | | community.docker | Docker container management | | ansible.windows | Windows automation | | community.vmware | VMware vSphere automation | | kubernetes.core | Kubernetes management | | ansible.netcommon | Network 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.

Related Articles

• Ansible Collections: What Are They and How to Use Them • Ansible Roles: Create Reusable Automation • Getting Started with Ansible