Where Are Ansible Collections Installed? Default Paths & Management

Ansible collections are modular packages that group related content such as roles, modules, and plugins. Understanding where collections are installed is essential for managing and customizing your Ansible automation workflows. This article explains the default installation paths for Ansible collections and how to customize them.

Where Are Ansible Collections Installed?

Default Installation Paths

By default, Ansible collections are installed in two primary locations depending on the type of user access: Global Path: For system-wide installation, collections are stored under the Ansible system directory:

   /usr/share/ansible/collections/
   

User Path: For user-specific installation, collections are stored in the user's home directory:

   ~/.ansible/collections/
   

This location is typically used when running ansible-galaxy collection install without administrative privileges.

Verifying Installed Collections

To view all installed collections, use the following command:

ansible-galaxy collection list

This command outputs the collection name, version, and installation path.

See also: What Are Ansible Collections? Modules, Roles & Plugins Packages (Guide)

How to Customize Collection Installation Paths

Ansible allows you to customize collection paths using the ANSIBLE_COLLECTIONS_PATHS environment variable or by modifying the ansible.cfg configuration file.

Using Environment Variables

Set a custom collection path using the ANSIBLE_COLLECTIONS_PATHS environment variable:

export ANSIBLE_COLLECTIONS_PATHS=/custom/path/to/collections

This variable overrides the default paths during collection installation and execution.

Updating the Configuration File

Modify the ansible.cfg file to define custom collection paths:

[defaults]
collections_paths = /custom/path/to/collections:/another/path

Multiple Paths

Ansible supports multiple collection paths. Specify them as a colon-separated list:

export ANSIBLE_COLLECTIONS_PATHS=/path1:/path2:/path3

The order of paths determines the priority when resolving collections.

Installing Collections in Custom Paths

To install collections in a specific directory, use the --collections-path option:

ansible-galaxy collection install my_namespace.my_collection --collections-path /custom/path

This option installs the collection in the specified path instead of the default directories.

See also: Ansible Collections: What They Are & How to Use Them (2026 Guide)

Why Customize Collection Paths?

Environment Isolation: Use custom paths to separate collections for different projects or environments. Shared Resources: Centralize collections in a shared directory for collaborative teams. Testing and Development: Use custom paths for developing and testing new collections.

Best Practices for Managing Collection Paths

Use Version Control: Store ansible.cfg or environment variables in version control to maintain consistency. Organize Paths: Separate production collections from test or development collections. Leverage Defaults: Use default paths for simplicity unless customization is necessary.

See also: What Are Ansible Roles: Complete Guide to Role Structure (2026)

Conclusion

Ansible collections are installed in user-specific or global directories by default, but you can customize their paths for better flexibility and organization. Whether you’re working in a shared environment or isolating collections for specific projects, understanding and managing collection paths ensures smooth automation workflows.

Learn More About Ansible Collections

Default Collection Paths

# Check configured paths
ansible-config dump | grep COLLECTIONS_PATH

| Path | Scope | |------|-------| | ~/.ansible/collections | User default | | /usr/share/ansible/collections | System-wide | | ./collections | Project-local |

Find Installed Collections

# List all installed collections
ansible-galaxy collection list
# Find a specific collection
ansible-galaxy collection list community.general
# Show collection path
ansible-galaxy collection list --format yaml

Install Collections

From Galaxy

ansible-galaxy collection install community.general
ansible-galaxy collection install amazon.aws:==7.0.0  # Specific version

From requirements.yml

# requirements.yml
collections:
  - name: community.general
    version: ">=8.0.0"
  - name: amazon.aws
    version: "7.0.0"
  - name: containers.podman

ansible-galaxy collection install -r requirements.yml

Custom install path

ansible-galaxy collection install community.general -p ./collections

From Git

ansible-galaxy collection install git+https://github.com/ansible-collections/community.general.git

Configure Collection Paths

ansible.cfg

[defaults]
collections_path = ./collections:~/.ansible/collections:/usr/share/ansible/collections

Environment variable

export ANSIBLE_COLLECTIONS_PATH=./collections:~/.ansible/collections

Collection Structure

~/.ansible/collections/ansible_collections/
  community/
    general/
      plugins/
        modules/
        filters/
      roles/
      docs/
      MANIFEST.json
  amazon/
    aws/
      ...

Project-Level Collections (recommended)

my-project/
  ansible.cfg        # collections_path = ./collections
  requirements.yml   # Collection dependencies
  collections/       # Project-local collections
  playbooks/
  roles/

This ensures consistent versions across team members and CI/CD.

FAQ

How do I update a collection?

ansible-galaxy collection install community.general --force
# Or specific version
ansible-galaxy collection install community.general:==9.0.0 --force

How do I remove a collection?

rm -rf ~/.ansible/collections/ansible_collections/community/general

There's no ansible-galaxy collection uninstall command (as of Ansible 2.17).

Which collection provides a specific module?

ansible-doc -l | grep module_name
# Or check the FQCN: ansible.builtin.copy = built-in, community.general.xxx = community.general

How do I use collections in playbooks?

# FQCN (recommended)
- community.general.timezone:
    name: UTC
# Or declare at play level
- hosts: all
  collections:
    - community.general
  tasks:
    - timezone:
        name: UTC

Related Articles

• requirements.yml with Ansible Galaxy • env var precedence in Ansible • the Ansible roles overview