Ansible Collections Path — Install Location

Introduction

The collections_paths setting in ansible.cfg controls where Ansible looks for and installs collections. Misconfiguring this path is the #1 reason for "collection not found" errors. This guide covers default locations, per-project isolation, and common path issues.

Default Collection Locations

Ansible searches for collections in this order:

1. ./collections/           (adjacent to playbook)
2. ~/.ansible/collections/  (user-level)
3. /usr/share/ansible/collections/  (system-wide)

# Check current paths
ansible-config dump | grep COLLECTIONS_PATHS
# COLLECTIONS_PATHS(default) = ['~/.ansible/collections', '/usr/share/ansible/collections']

Configure in ansible.cfg

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

# Or via environment variable
export ANSIBLE_COLLECTIONS_PATHS=./collections:~/.ansible/collections

Per-Project Collection Isolation

my-project/
├── ansible.cfg
├── collections/           ← Project-local collections
│   └── ansible_collections/
│       ├── community/
│       │   └── general/
│       └── amazon/
│           └── aws/
├── requirements.yml
└── playbooks/

# ansible.cfg
[defaults]
collections_paths = ./collections

# Install to project-local directory
ansible-galaxy collection install -r requirements.yml -p ./collections

# Verify installation
ls collections/ansible_collections/

requirements.yml

# requirements.yml
collections:
  - name: community.general
    version: ">=9.0.0"
  - name: amazon.aws
    version: ">=10.0.0"
  - name: ansible.netcommon
    version: ">=9.0.0"
  - name: community.docker
    version: ">=4.0.0"

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

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

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

Collection Directory Structure

collections/
└── ansible_collections/
    └── namespace/
        └── collection_name/
            ├── galaxy.yml
            ├── plugins/
            │   ├── modules/
            │   ├── inventory/
            │   └── callback/
            ├── roles/
            ├── playbooks/
            └── docs/

Find Where a Collection Is Installed

# Show collection location
ansible-galaxy collection list

# Find specific collection
ansible-galaxy collection list community.general
# Collection     Version Path
# -------------- ------- ----
# community.general 9.5.0  /home/user/.ansible/collections/ansible_collections

# Verbose: show all search paths
ansible-galaxy collection list -vvv

Common Errors and Fixes

Error	Cause	Fix
`ERROR! couldn't resolve module/action`	Collection not in search path	Check `collections_paths` includes install location
`ModuleNotFoundError`	Collection installed in wrong path	Install with `-p` matching your config
`ERROR! the role was not found in`	Role in collection, path mismatch	Ensure `collections_paths` is correct
Multiple versions conflict	Different paths have different versions	Use project-local path only
`ansible-galaxy: error: unrecognized arguments`	Old ansible version	Upgrade to ansible-core 2.15+

CI/CD Pattern

# GitHub Actions
- name: Install collections
  run: |
    ansible-galaxy collection install -r requirements.yml -p ./collections
  env:
    ANSIBLE_COLLECTIONS_PATHS: ./collections

- name: Run playbook
  run: ansible-playbook -i inventory site.yml
  env:
    ANSIBLE_COLLECTIONS_PATHS: ./collections

Python Virtual Environment Pattern

# Create venv with collections isolated
python3 -m venv .venv
source .venv/bin/activate
pip install ansible-core

# Install collections to venv
ansible-galaxy collection install -r requirements.yml \
  -p .venv/lib/python3.12/site-packages/ansible_collections/

# Or simpler: use project-local
ansible-galaxy collection install -r requirements.yml -p ./collections

Execution Environments

# execution-environment.yml
dependencies:
  galaxy: requirements.yml
  python: requirements.txt

# Collections automatically bundled inside EE
# No path configuration needed at runtime

# Build EE with collections baked in
ansible-builder build -t my-ee:latest
ansible-navigator run site.yml --eei my-ee:latest

Best Practices

Use project-local ./collections — reproducible across machines
Pin versions in requirements.yml — avoid surprise upgrades
Set collections_paths in ansible.cfg — not just env vars
Commit requirements.yml, not the collections — install in CI
Use one path — avoid confusion from multiple search locations
Add collections/ to .gitignore — install fresh each time

Conclusion

Set collections_paths in ansible.cfg to control where Ansible finds collections. Use project-local ./collections for isolation, install from requirements.yml with pinned versions, and verify with ansible-galaxy collection list. The most common "module not found" errors trace back to a path mismatch between install location and search path.