AnsibleByExample

Ansible COLLECTIONS_PATH — Configure

Beginneransiblecollectionsconfigurationansible-galaxy
2024-01-013By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

Default Collections Paths

Ansible looks for collections in these locations (in order):

  1. ./collections/ansible_collections/ (project-local)
  2. ~/.ansible/collections/ansible_collections/ (user-local)
  3. /usr/share/ansible/collections/ansible_collections/ (system-wide)

Configure in ansible.cfg

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

Multiple paths are separated by colons (:) on Linux/macOS or semicolons (;) on Windows.

Configure with Environment Variable

# Set for current session
export ANSIBLE_COLLECTIONS_PATHS=./collections:~/.ansible/collections

# Or add to ~/.bashrc or ~/.zshrc
echo 'export ANSIBLE_COLLECTIONS_PATHS=./collections:~/.ansible/collections' >> ~/.bashrc

Install Collections to a Specific Path

# Install to project-local directory
ansible-galaxy collection install community.docker -p ./collections

# Install to custom path
ansible-galaxy collection install community.vmware -p /opt/ansible/collections

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

requirements.yml

---
collections:
  - name: community.docker
    version: ">=3.0.0"
  - name: community.postgresql
  - name: amazon.aws
    version: "7.0.0"
  - name: kubernetes.core

Show Installed Collections

# List all installed collections
ansible-galaxy collection list

# Show collections in a specific path
ansible-galaxy collection list -p ./collections

# Show details for a specific collection
ansible-galaxy collection list community.docker

Output:

# /home/user/.ansible/collections/ansible_collections
Collection               Version
------------------------ -------
community.docker         3.8.0
community.general        8.5.0
community.postgresql     3.4.0
ansible.posix            1.5.4

Verify Collection Installation

# Check if a module is available
ansible-doc community.docker.docker_container

# Search for modules
ansible-doc -l | grep docker

Project Structure with Local Collections

my-project/
├── ansible.cfg
├── collections/
│   └── ansible_collections/
│       ├── community/
│       │   ├── docker/
│       │   └── postgresql/
│       └── amazon/
│           └── aws/
├── inventory/
├── playbooks/
└── requirements.yml

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

Fix "Collection Not Found" Errors

Error: "couldn't resolve module/action"

ERROR! couldn't resolve module/action 'community.docker.docker_container'

Fix:

# 1. Install the collection
ansible-galaxy collection install community.docker

# 2. Verify it's installed
ansible-galaxy collection list community.docker

# 3. Check your collections_paths
ansible-config dump | grep COLLECTIONS_PATHS

Error: "collection not found in configured paths"

Your collections_paths doesn't include where the collection is installed:

# Check where collections are installed
ansible-galaxy collection list

# Check configured paths
ansible-config dump | grep COLLECTIONS_PATHS

# Add the correct path to ansible.cfg

ANSIBLE_COLLECTIONS_PATH vs ANSIBLE_COLLECTIONS_PATHS

Both work — ANSIBLE_COLLECTIONS_PATHS (plural) is the standard. The singular form is also accepted as an alias for backward compatibility.

# Both are equivalent
export ANSIBLE_COLLECTIONS_PATHS=./collections
export ANSIBLE_COLLECTIONS_PATH=./collections

In ansible.cfg, use collections_paths (plural):

[defaults]
collections_paths = ./collections:~/.ansible/collections

Browse 800+ Ansible tutorials on AnsibleByExample.

All Tutorials