ansible-galaxy install: Usage & Common CI Errors

Install the roles and collections your playbooks depend on.

ansible-galaxy install pulls roles and collections from Ansible Galaxy, Git, or a private hub. In CI you install everything pinned in requirements.yml before running a playbook.

What it does

ansible-galaxy install -r requirements.yml downloads the roles listed in a requirements file into the roles path; ansible-galaxy collection install -r requirements.yml installs collections into the collections path. Pinning versions in requirements.yml makes CI reproducible.

Common usage

# Install roles from a requirements file
ansible-galaxy install -r requirements.yml

# Install collections (note the explicit subcommand)
ansible-galaxy collection install -r requirements.yml

# Force reinstall into a specific path (CI cache dir)
ansible-galaxy install -r requirements.yml --force -p ./roles

Common error in CI: roles installed but collections missing

A playbook fails with "couldn’t resolve module/action ... namespace.collection" even though ansible-galaxy install -r requirements.yml ran clean. Plain install only handles roles; collections need the collection subcommand. Fix: run BOTH ansible-galaxy role install -r requirements.yml and ansible-galaxy collection install -r requirements.yml, or use a requirements.yml with top-level roles: and collections: keys and install each. Pin versions so CI does not silently pull a breaking major.

Key options

Related guides