Ansible Collections Requirements — Install and Manage Dependencies

Introduction

Modern Ansible uses collections for modules, plugins, and roles. A requirements.yml file pins the exact collections your project needs — ensuring consistent behavior across teams, CI/CD pipelines, and production environments. Without it, ansible-galaxy installs whatever version is latest, leading to breaking changes and unreproducible builds.

Basic requirements.yml

---
collections:
  - name: community.general
    version: ">=9.0.0,<10.0.0"

  - name: community.postgresql
    version: "3.7.0"

  - name: amazon.aws
    version: "8.2.0"

  - name: ansible.posix
    version: ">=1.5.0"

  - name: community.docker
    version: "4.0.0"

Install Collections

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

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

# Install to specific path
ansible-galaxy collection install -r requirements.yml -p ./collections

# Upgrade to latest within version constraints
ansible-galaxy collection install -r requirements.yml --upgrade

Version Pinning Strategies

collections:
  # Exact version (most reproducible)
  - name: community.general
    version: "9.5.0"

  # Minimum version
  - name: ansible.posix
    version: ">=1.5.0"

  # Range (semantic versioning)
  - name: amazon.aws
    version: ">=8.0.0,<9.0.0"

  # Any version (not recommended)
  - name: community.docker

  # Latest compatible (pessimistic)
  - name: community.postgresql
    version: ">=3.7.0,<4.0.0"

When to Use Which

Strategy	When	Risk
Exact `"9.5.0"`	Production, CI/CD	Misses security updates
Range `">=9.0,<10.0"`	Most projects	Controlled updates within major
Minimum `">=9.0"`	Development	May break on major updates
No version	Quick testing only	Unpredictable behavior

Mixed Roles and Collections

---
collections:
  - name: community.general
    version: "9.5.0"
  - name: amazon.aws
    version: "8.2.0"
  - name: community.postgresql
    version: "3.7.0"

roles:
  - name: geerlingguy.nginx
    version: "3.2.0"
  - name: geerlingguy.postgresql
    version: "7.0.0"
  - src: https://github.com/org/custom-role.git
    scm: git
    version: v2.0.0
    name: custom_role

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

Private Automation Hub / Galaxy Server

collections:
  # From default Galaxy
  - name: community.general
    version: "9.5.0"

  # From private Automation Hub
  - name: myorg.internal_collection
    version: "1.2.0"
    source: https://hub.example.com/api/galaxy/content/published/

  # From alternative Galaxy server
  - name: custom.collection
    source: https://galaxy.custom.com/

Configure servers in ansible.cfg

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy

[galaxy_server.automation_hub]
url = https://hub.example.com/api/galaxy/content/published/
token = your-token-here

[galaxy_server.galaxy]
url = https://galaxy.ansible.com/

Install from Git

collections:
  # From Git repository
  - name: https://github.com/org/my-collection.git
    type: git
    version: main

  # Specific tag
  - name: https://github.com/org/my-collection.git
    type: git
    version: v1.5.0

Install from Tarball

collections:
  # Local tarball
  - name: /path/to/my_namespace-my_collection-1.0.0.tar.gz
    type: file

  # Remote tarball
  - name: https://releases.example.com/collections/myorg-myapp-2.0.0.tar.gz
    type: url

Project Setup

my-ansible-project/
├── ansible.cfg
├── requirements.yml          # Collection/role dependencies
├── collections/
│   └── ansible_collections/  # Installed collections go here
├── roles/
│   └── requirements.yml      # Role-only dependencies (optional)
├── inventory/
├── playbooks/
└── group_vars/

# ansible.cfg
[defaults]
collections_path = ./collections:~/.ansible/collections
roles_path = ./roles:~/.ansible/roles

CI/CD Integration

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Ansible
        run: pip install ansible-core

      - name: Install collections
        run: ansible-galaxy collection install -r requirements.yml -p ./collections

      - name: Run playbook
        run: ansible-playbook -i inventory/production playbooks/deploy.yml

# Makefile
.PHONY: setup deploy

setup:
	pip install ansible-core
	ansible-galaxy collection install -r requirements.yml --force

deploy: setup
	ansible-playbook -i inventory/production playbooks/deploy.yml

List and Verify

# List installed collections
ansible-galaxy collection list

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

# Show collection info
ansible-galaxy collection list community.general

# Check for updates
ansible-galaxy collection install -r requirements.yml --upgrade --dry-run

Troubleshooting

Issue	Solution
"Collection not found"	Check `collections_path` in ansible.cfg
Version conflict	Pin exact versions; check dependency chains
"ERROR! Unexpected Exception"	Upgrade ansible-core; collection may need newer version
Private hub auth fails	Check token in ansible.cfg `[galaxy_server.xxx]`
Slow installs	Use `--no-deps` if you manage dependencies manually
Can't find modules	Ensure `collections_path` includes install directory

Best Practices

Always use requirements.yml — reproducible builds
Pin major.minor version ranges — ">=9.0.0,<10.0.0" for stability
Commit requirements.yml — version control your dependencies
Don't commit collections/ — install at build time
Use --force in CI/CD — ensure clean installs
Review changelogs before upgrading — check breaking changes
Separate dev/prod requirements — requirements-dev.yml for testing tools

Conclusion

requirements.yml is your Ansible project's dependency manifest. Pin collection versions for reproducible builds, configure private registries for internal collections, and automate installation in CI/CD pipelines. Without it, you're relying on whatever version happens to be installed — a recipe for "works on my machine" problems.