AnsibleByExample

Fix Ansible Galaxy Install Errors

BeginnerAnsible GalaxyAmazon AWStroubleshootinginstallation error
2024-01-014By Luca Berton

Lesson 1 of 25 in AWS Automation

AWS with Ansible — full curriculum
  1. 1. AWS Basics for Ansible
  2. 2. Installing the amazon.aws Collection and boto3
  3. 3. AWS Credentials and Profiles: Safe Configuration
  4. 4. Your First AWS Playbook: Regions, Tags and Idempotency
  5. 5. AWS Dynamic Inventory with the aws_ec2 Plugin
  6. 6. Grouping and Filtering Hosts with keyed_groups and Filters
  7. 7. Provisioning EC2 Instances
  8. 8. AMIs and Launch Templates
  9. 9. Building VPC Networks with Ansible
  10. 10. Security Groups and Network Access Control
  11. 11. Elastic IPs and Load Balancers
  12. 12. S3 Buckets and Object Management
  13. 13. IAM Users, Roles and Policies
  14. 14. RDS Databases with Ansible
  15. 15. Route 53 DNS Automation
  16. 16. CloudWatch Monitoring and Alarms
  17. 17. Managing Secrets: Secrets Manager, SSM Parameter Store and Ansible Vault
  18. 18. Post-Provisioning Configuration with Roles
  19. 19. Bridging Provisioning and Configuration: add_host and wait_for
  20. 20. Auto Scaling Groups and Rolling Updates
  21. 21. Validating Infrastructure with Assertions and Health Checks
  22. 22. Error Handling and Rollback in AWS Playbooks
  23. 23. Structuring a Reusable AWS Automation Project
  24. 24. Cost Control and Teardown Playbooks
  25. 25. Capstone: Provision and Configure a Multi-Tier AWS Application
View path overview →

Introduction

A common Ansible Galaxy error occurs when users try to install a collection using the role install command. The ansible-galaxy install command defaults to roles, but most modern Ansible content (like amazon.aws) is packaged as collections. Understanding the difference prevents frustrating "not found" errors.

The Error

$ ansible-galaxy install amazon.aws
Starting galaxy role install process
- downloading role 'aws', owned by amazon
[WARNING]: - amazon.aws was NOT installed successfully: - sorry, amazon.aws was not
found on https://galaxy.ansible.com/api/.
ERROR! - you can use --ignore-errors to skip failed roles and finish processing the list.

Root Cause: Roles vs Collections

Content TypeInstall CommandExample
Roleansible-galaxy installansible-galaxy install geerlingguy.docker
Collectionansible-galaxy collection installansible-galaxy collection install amazon.aws

amazon.aws is a collection, not a role. The role install command looks in a different API endpoint, finds nothing, and fails.

The Fix

# WRONG — looks for a role named amazon.aws
ansible-galaxy install amazon.aws

# CORRECT — installs the amazon.aws collection
ansible-galaxy collection install amazon.aws

Successful output:

$ ansible-galaxy collection install amazon.aws
Starting galaxy collection install process
Process install dependency map
Starting collection install process
Downloading https://galaxy.ansible.com/.../amazon-aws-7.2.0.tar.gz
Installing 'amazon.aws:7.2.0' to '/home/user/.ansible/collections/ansible_collections/amazon/aws'
amazon.aws:7.2.0 was installed successfully

Install Specific Version

# Latest version
ansible-galaxy collection install amazon.aws

# Specific version
ansible-galaxy collection install amazon.aws:==7.2.0

# Minimum version
ansible-galaxy collection install 'amazon.aws:>=7.0.0'

Manage all dependencies in a single file:

# requirements.yml
---
collections:
  - name: amazon.aws
    version: ">=7.0.0"
  - name: community.general
  - name: ansible.posix
  - name: community.docker

roles:
  - name: geerlingguy.docker
  - name: geerlingguy.nginx

Install everything:

# Install both roles and collections from requirements file
ansible-galaxy install -r requirements.yml
ansible-galaxy collection install -r requirements.yml

# Or use the combined command
ansible-galaxy install -r requirements.yml --roles-path roles/
ansible-galaxy collection install -r requirements.yml

Common Errors and Fixes

"Not found on Galaxy API"

amazon.aws was NOT installed successfully: - sorry, amazon.aws was not found

Fix: Use collection install instead of install.

Network/Timeout Errors

ERROR! Unexpected Exception, this is probably a bug: ('Connection aborted.')

Fixes:

# Retry with verbose output
ansible-galaxy collection install amazon.aws -vvv

# Use a different Galaxy server
ansible-galaxy collection install amazon.aws --server https://galaxy.ansible.com

# Set timeout
ansible-galaxy collection install amazon.aws --timeout 120

# Install from tarball (offline)
ansible-galaxy collection install ./amazon-aws-7.2.0.tar.gz

Version Compatibility

ERROR! Cannot satisfy collection requirement amazon.aws:>=8.0.0

Fix: Check which versions are available:

# List available versions
ansible-galaxy collection list amazon.aws 2>/dev/null || echo "Not installed"

# Search on Galaxy
# https://galaxy.ansible.com/ui/repo/published/amazon/aws/

"requires_ansible" Metadata Error

[WARNING]: Error parsing collection metadata requires_ansible value

This warning is usually harmless — it comes from another installed collection with a malformed metadata field. The target collection still installs correctly.

Permission Errors

# Install to user directory (no sudo needed)
ansible-galaxy collection install amazon.aws -p ~/.ansible/collections

# Or set in ansible.cfg
# [defaults]
# collections_paths = ~/.ansible/collections:/usr/share/ansible/collections

Managing Installed Collections

# List installed collections
ansible-galaxy collection list

# List specific collection
ansible-galaxy collection list amazon.aws

# Verify collection integrity
ansible-galaxy collection verify amazon.aws

# Remove a collection
rm -rf ~/.ansible/collections/ansible_collections/amazon/aws

# Force reinstall
ansible-galaxy collection install amazon.aws --force
CollectionPurpose
amazon.awsAWS cloud management
azure.azcollectionAzure cloud management
google.cloudGCP management
community.generalGeneral-purpose modules
community.dockerDocker management
community.vmwareVMware vSphere
ansible.posixPOSIX system modules
ansible.netcommonNetwork automation base
ansible.windowsWindows modules
community.postgresqlPostgreSQL management

Conclusion

The #1 Galaxy installation mistake: using ansible-galaxy install for collections. Collections require ansible-galaxy collection install. Use requirements.yml to manage all dependencies (roles and collections) in one place, pin versions for reproducibility, and always check whether content is a role or collection before installing.

All Tutorials