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

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

How to install Ansible collections and roles from Galaxy. Use ansible-galaxy install, requirements.yml, manage dependencies, offline install.

Ansible Galaxy is the community hub for finding, sharing, and using Ansible roles and collections. The ansible-galaxy CLI tool installs content from Galaxy, Git repos, and tarballs — it's like pip or npm for Ansible.

Install Roles

From Galaxy

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

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

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

From Git

# From GitHub
ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-docker.git

# Specific branch/tag
ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-docker.git,main

From requirements.yml

# requirements.yml
---
roles:
  - name: geerlingguy.docker
    version: "6.1.0"
  - name: geerlingguy.nginx
  - name: geerlingguy.certbot

collections:
  - name: community.docker
    version: ">=3.0.0"
  - name: ansible.windows
  - name: community.general

# Install everything from requirements.yml
ansible-galaxy install -r requirements.yml

# Install roles only
ansible-galaxy role install -r requirements.yml

# Install collections only
ansible-galaxy collection install -r requirements.yml

# Force reinstall
ansible-galaxy install -r requirements.yml --force

Install Collections

# Install collection
ansible-galaxy collection install community.docker

# Install specific version
ansible-galaxy collection install community.docker:3.8.0

# Install from requirements.yml
ansible-galaxy collection install -r requirements.yml

# Install to custom path
ansible-galaxy collection install community.docker -p ./collections/

Create a New Role

Initialize Role Structure

# Create role skeleton
ansible-galaxy role init my_webserver

# Creates:
# my_webserver/
# ├── defaults/main.yml       # Default variables
# ├── files/                   # Static files
# ├── handlers/main.yml        # Handlers
# ├── meta/main.yml            # Role metadata
# ├── README.md                # Documentation
# ├── tasks/main.yml           # Tasks
# ├── templates/               # Jinja2 templates
# ├── tests/
# │   ├── inventory
# │   └── test.yml
# └── vars/main.yml            # Role variables

Role Structure Explained

# defaults/main.yml — Defaults (easily overridden)
---
http_port: 80
max_workers: 4
document_root: /var/www/html

# vars/main.yml — Internal variables (hard to override)
---
_nginx_packages:
  - nginx
  - nginx-extras

# tasks/main.yml — Main task list
---
- name: Install packages
  ansible.builtin.package:
    name: "{{ _nginx_packages }}"
    state: present

- name: Deploy configuration
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: restart nginx

- name: Start service
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

# handlers/main.yml — Handlers
---
- name: restart nginx
  ansible.builtin.service:
    name: nginx
    state: restarted

# meta/main.yml — Metadata and dependencies
---
galaxy_info:
  author: Luca Berton
  description: Install and configure Nginx
  license: MIT
  min_ansible_version: "2.15"
  platforms:
    - name: Ubuntu
      versions: [jammy, noble]
    - name: EL
      versions: [8, 9]
  galaxy_tags:
    - nginx
    - webserver

dependencies:
  - role: common

Use Your Role

# playbook.yml
- hosts: webservers
  roles:
    - my_webserver

# With variables
- hosts: webservers
  roles:
    - role: my_webserver
      vars:
        http_port: 8080
        max_workers: 8

Create a Collection

# Initialize collection
ansible-galaxy collection init my_namespace.my_collection

# Creates:
# my_namespace/my_collection/
# ├── docs/
# ├── galaxy.yml              # Collection metadata
# ├── meta/runtime.yml
# ├── plugins/
# │   └── README.md
# ├── README.md
# └── roles/

Manage Installed Content

# List installed roles
ansible-galaxy role list

# List installed collections
ansible-galaxy collection list

# Remove a role
ansible-galaxy role remove geerlingguy.docker

# Verify collection integrity
ansible-galaxy collection verify community.docker

Search Galaxy

# Search for roles
ansible-galaxy role search nginx
ansible-galaxy role search nginx --platforms Ubuntu

# Search for collections
ansible-galaxy collection list  # (search on galaxy.ansible.com website)

# Get role info
ansible-galaxy role info geerlingguy.docker

Publish to Galaxy

Publish a Role

# 1. Create a GitHub repo named ansible-role-<name>
# 2. Push your role code
# 3. Import on Galaxy:
#    - Go to galaxy.ansible.com
#    - Log in with GitHub
#    - Import your repo

# Or via CLI (legacy)
ansible-galaxy role import github_user repo_name

Publish a Collection

# Build the collection
ansible-galaxy collection build

# Publish to Galaxy
ansible-galaxy collection publish my_namespace-my_collection-1.0.0.tar.gz --api-key=<your-key>

Private Galaxy / Automation Hub

# Install from private Galaxy
ansible-galaxy collection install my_namespace.my_collection \
  --server https://galaxy.example.com/api/

# Configure in ansible.cfg
# [galaxy]
# server_list = private_galaxy, galaxy
#
# [galaxy_server.private_galaxy]
# url=https://galaxy.example.com/api/
# token=my-token
#
# [galaxy_server.galaxy]
# url=https://galaxy.ansible.com/

Best Practices

Always use requirements.yml — Version-lock dependencies for reproducible builds
Pin versions — version: "6.1.0" not just the name
Use FQCNs in roles — ansible.builtin.copy not copy
Put defaults in defaults/ — Easy to override; keep vars/ for internal constants
Document with README.md — Include variables, examples, and requirements
Test with Molecule — Verify roles work across platforms
Tag releases — Use semantic versioning for your roles

FAQ

What is Ansible Galaxy?

Ansible Galaxy (galaxy.ansible.com) is a public repository of community-contributed Ansible roles and collections. The ansible-galaxy CLI tool downloads and manages this content locally.

What is the difference between roles and collections?

Roles package tasks, handlers, variables, and templates for a single function (e.g., "install nginx"). Collections bundle multiple roles, modules, plugins, and playbooks into a namespace (e.g., community.docker with multiple Docker modules).

How do I create a requirements.yml?

List roles and collections with their versions. Use ansible-galaxy install -r requirements.yml to install everything. This is the Ansible equivalent of package.json or requirements.txt.

How do I install roles from a private Git repository?

Use the src field with a Git URL in requirements.yml: src: git@github.com:myorg/my-role.git. Add scm: git and optionally version for a specific branch or tag.

Where are Galaxy roles installed?

Default: ~/.ansible/roles/. Override with -p ./roles/ flag or roles_path in ansible.cfg. Collections install to ~/.ansible/collections/ by default.

Conclusion

ansible-galaxy role install — Install community roles
ansible-galaxy collection install — Install module collections
requirements.yml — Version-lock all dependencies
ansible-galaxy role init — Scaffold a new role
Always pin versions for reproducible automation

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton