Ansible Galaxy: Install Roles and Collections

Ansible Galaxy is the public hub for sharing and downloading Ansible content — both reusable roles and, since Ansible 2.10, collections. You pull content from it with the ansible-galaxy command-line tool, pin what you depend on in a requirements.yml file, and (optionally) publish your own content back to the community at galaxy.ansible.com.

If you are new to Ansible itself, start with our practical guide to Ansible for server automation, then come back here to learn how Galaxy lets you reuse other people's work instead of writing every playbook from scratch.

Key takeaways

• Ansible Galaxy is the community registry for Ansible content; the ansible-galaxy CLI ships with Ansible.
• Galaxy distributes two kinds of content: roles (one reusable unit of automation) and collections (bundles of roles, modules, and plugins under a namespace).
• Since Ansible 2.10 the project split into ansible-core plus content collections; most modules now live in collections and are referenced by their FQCN (e.g. community.general.timezone, ansible.posix.cron).
• Install content with ansible-galaxy role install <namespace.role> or ansible-galaxy collection install <namespace.collection>, and declare dependencies in a single requirements.yml.
• Scaffold a new role with ansible-galaxy init <role_name>, which creates the standard tasks/, handlers/, defaults/, vars/, templates/, meta/ layout.
• Red Hat Automation Hub is the certified, supported counterpart to the community Galaxy hub.

What is Ansible Galaxy?

Ansible Galaxy is a public repository of community-contributed automation content, hosted at galaxy.ansible.com. Instead of writing a playbook to install and configure, say, Docker or PostgreSQL by hand, you can install a battle-tested role or collection that already does it and call it from your own playbooks.

The ansible-galaxy command bundled with every Ansible install is the client for this hub. It can search, download, scaffold, build, and publish content.

Ansible Galaxy after the ansible-core split

This is the most important modern fact, and the one most older tutorials get wrong. Up to Ansible 2.9, "Ansible" shipped as one monolithic package with every module built in. Since Ansible 2.10, the project split into two pieces:

1. ansible-core — the engine, the language, and a small set of built-in modules under the ansible.builtin namespace.
2. Collections — everything else (most modules and plugins) packaged into versioned, namespaced bundles such as community.general, ansible.posix, and community.mysql.

Because of this split, most modules are now referenced by their Fully Qualified Collection Name (FQCN): namespace.collection.module. Ansible Galaxy is how you obtain those collections. The ansible package on PyPI is a curated bundle of ansible-core plus many popular collections, while ansible-core alone ships only ansible.builtin.

Roles vs collections: what is the difference?

A role is a single, self-contained unit of automation (one app or one configuration concern). A collection is a larger distribution format that can package many roles plus the modules, plugins, and playbooks they need, all under one namespace.

	Role	Collection
Bundles	tasks, handlers, defaults, vars, templates, files, meta for one unit	multiple roles + modules + plugins + playbooks under a namespace
Install command	ansible-galaxy role install namespace.role	ansible-galaxy collection install namespace.collection
Referenced as	role name in roles: / include_role	module FQCN namespace.collection.module
Introduced	classic format (pre-2.10)	the default packaging since Ansible 2.10
Versioning	git tag / Galaxy version	SemVer in galaxy.yml
Use when	packaging one reusable configuration unit	shipping modules/plugins or a suite of related content

Rule of thumb: if you only have tasks and templates for one job, a role is enough. If you ship custom modules/plugins or several related roles, package them as a collection.

How do I install a role from Ansible Galaxy?

Use ansible-galaxy role install (or just ansible-galaxy install, which defaults to roles) with the namespace.role_name:

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

# Install a specific version
ansible-galaxy role install geerlingguy.mysql,3.3.0

# See where roles are installed and list them
ansible-galaxy role list

By default roles land in ~/.ansible/roles (or the first path in roles_path from your ansible.cfg). Once installed, reference the role by name in a play:

---
- hosts: db_servers
  become: true
  roles:
    - geerlingguy.mysql

How do I install a collection from Ansible Galaxy?

Collections are the modern default. Install them with ansible-galaxy collection install and reference their modules by FQCN:

# Install a collection
ansible-galaxy collection install community.general

# Pin an exact version
ansible-galaxy collection install community.general:8.6.0

# Install into a project-local path
ansible-galaxy collection install ansible.posix -p ./collections

Now you can call any module the collection provides via its FQCN — no extra configuration needed:

---
- name: Use a module from a collection via FQCN
  hosts: all
  become: true
  tasks:
    - name: Manage a cron job (from the ansible.posix collection)
      ansible.posix.cron:
        name: "nightly backup"
        minute: "0"
        hour: "2"
        job: "/usr/local/bin/backup.sh"

Pinning dependencies in requirements.yml

A requirements.yml file lets you declare every role and collection your project needs, with versions, so teammates and CI install identical content. A single file can hold both roles: and collections: sections:

---
# requirements.yml
roles:
  - name: geerlingguy.mysql
    version: "3.3.0"
  - src: https://github.com/example-org/ansible-role-myapp
    scm: git
    version: main
    name: myapp

collections:
  - name: community.general
    version: ">=8.0.0"
  - name: ansible.posix
  - name: community.mysql

Install everything in one shot. Since Ansible 2.10, ansible-galaxy install -r requirements.yml reads both sections of a combined file; you can also target one type explicitly:

# Install BOTH roles and collections from a combined file
ansible-galaxy install -r requirements.yml

# Or target one type at a time
ansible-galaxy role install -r requirements.yml
ansible-galaxy collection install -r requirements.yml

How do I create a role with ansible-galaxy init?

Run ansible-galaxy init to scaffold the standard role directory layout:

ansible-galaxy init mysql_server

This generates a predictable structure that Ansible knows how to load automatically:

mysql_server/
├── defaults/main.yml      # default variables (lowest precedence)
├── files/                 # static files to copy
├── handlers/main.yml      # handlers triggered via "notify"
├── meta/main.yml          # role metadata + dependencies
├── tasks/main.yml         # the core logic (entry point)
├── templates/             # Jinja2 templates
├── tests/                 # inventory + test playbook
├── vars/main.yml          # role variables (higher precedence)
└── README.md

Each directory has a specific job:

Directory	What it holds
defaults/	Default variables a user can easily override (lowest precedence).
vars/	Role variables with higher precedence than defaults.
tasks/	The core list of tasks; main.yml is the entry point.
handlers/	Tasks invoked only when notify'd (e.g. restart a service after a config change).
templates/	Jinja2 templates rendered into config files on the host.
files/	Static files copied to the host verbatim.
meta/	Role metadata: author, license, supported platforms, and role dependencies.

Worked example: a MySQL role

Here is the classic "install MySQL on Ubuntu" role brought up to current standards — FQCN module names (ansible.builtin.*), the loop keyword instead of the deprecated with_items, and the modern default-libmysqlclient-dev package.

First, set the password variable in vars/main.yml (use Ansible Vault for real secrets):

---
# mysql_server/vars/main.yml
mysql_server_password: "change_me_with_ansible_vault"

Then write the tasks in tasks/main.yml:

---
# mysql_server/tasks/main.yml
- name: Preseed MySQL root password
  ansible.builtin.debconf:
    name: mysql-server
    question: mysql-server/root_password
    value: "{{ mysql_server_password }}"
    vtype: password

- name: Confirm MySQL root password
  ansible.builtin.debconf:
    name: mysql-server
    question: mysql-server/root_password_again
    value: "{{ mysql_server_password }}"
    vtype: password

- name: Install MySQL packages
  ansible.builtin.apt:
    name:
      - mysql-server
      - default-libmysqlclient-dev
    state: present
    update_cache: true
  when: ansible_os_family == 'Debian'

Finally, a top-level playbook (site.yml next to the role) applies it to your hosts:

---
# site.yml
- hosts: db_servers
  become: true
  roles:
    - mysql_server

Run it with ansible-playbook -i inventory site.yml and MySQL is installed on every host in the db_servers group. For a fuller end-to-end deployment using roles, see our walkthrough on deploying Django with uWSGI, Nginx and Ansible.

Ansible Galaxy vs Red Hat Automation Hub

Galaxy is the free community hub. For enterprises that need certified, supported content, Red Hat ships Automation Hub as part of the Ansible Automation Platform.

	Ansible Galaxy	Red Hat Automation Hub
Type	Public, community hub	Certified / supported content
Content	Community roles & collections	Red Hat-certified and validated collections
Hosting	galaxy.ansible.com	console.redhat.com, or a private Automation Hub you self-host
Support	Best-effort, community-maintained	Backed by a Red Hat Ansible Automation Platform subscription
Best for	Prototyping, open-source modules, learning	Production estates needing SLAs and supported content

You can point the ansible-galaxy client at either source (or both) by configuring server_list in ansible.cfg.

How do I publish to Ansible Galaxy?

Galaxy supports both content types, but the workflows differ.

To publish a collection (the modern path): define a galaxy.yml with your namespace, name, and version, build a tarball, then publish it with your Galaxy API token:

# Build the collection tarball
ansible-galaxy collection build

# Publish it to Galaxy (token from your galaxy.ansible.com account)
ansible-galaxy collection publish ./my_namespace-my_collection-1.0.0.tar.gz --api-key=<YOUR_TOKEN>

To publish a role: push it to a public GitHub repository, sign in to galaxy.ansible.com with your GitHub account to claim a namespace, then import it:

ansible-galaxy role import github_user repository_name

Note: the legacy ansible-galaxy pull command from older tutorials does not exist. To consume content, use ansible-galaxy install / ansible-galaxy collection install as shown above.

Once published, anyone can install your content with a single ansible-galaxy command. If you would rather have the automation built and maintained for you, our server maintenance services cover provisioning, hardening, and Ansible-driven configuration management.

Frequently Asked Questions

What is Ansible Galaxy used for?

Ansible Galaxy is the public hub where the community shares reusable Ansible content. You use it to download ready-made roles and collections instead of writing every playbook from scratch, to pin those dependencies in a requirements.yml, and to publish your own content for others to reuse. The ansible-galaxy CLI that talks to it ships with Ansible.

What is the difference between a role and a collection in Ansible Galaxy?

A role is a single, self-contained unit of automation — its tasks, handlers, variables, and templates for one job. A collection is a larger format that bundles multiple roles plus modules, plugins, and playbooks under one namespace. Install a role with ansible-galaxy role install namespace.role and a collection with ansible-galaxy collection install namespace.collection.

How do I install a collection from Ansible Galaxy?

Run ansible-galaxy collection install namespace.collection, for example ansible-galaxy collection install community.general. Add :VERSION to pin a release (community.general:8.6.0) or -r requirements.yml to install everything declared in a requirements file. After installing, call the collection's modules by their FQCN, such as community.general.timezone.

What is an FQCN in Ansible?

FQCN stands for Fully Qualified Collection Name — the namespace.collection.module form used to reference a module unambiguously, for example ansible.builtin.copy, ansible.posix.cron, or community.mysql.mysql_user. Since the Ansible 2.10 split into ansible-core plus collections, FQCNs are the recommended way to call modules so Ansible always resolves the right one.

What is the difference between Ansible Galaxy and Red Hat Automation Hub?

Ansible Galaxy is the free, public, community-maintained hub at galaxy.ansible.com. Red Hat Automation Hub is the certified, supported counterpart distributed with the Red Hat Ansible Automation Platform; it hosts Red Hat-certified and validated collections and is aimed at production estates that need vendor support and SLAs. The same ansible-galaxy client can install from either source.

How do I publish a role or collection to Ansible Galaxy?

For a collection, define galaxy.yml, run ansible-galaxy collection build, then ansible-galaxy collection publish <tarball> --api-key=<token>. For a role, push it to a public GitHub repo, sign in to galaxy.ansible.com with GitHub to claim your namespace, then run ansible-galaxy role import github_user repo. Note that the old ansible-galaxy pull command does not exist.