Collections

Galaxy collections are the modern packaging format for Ansible content — modules, plugins, roles, and playbooks bundled into versioned, namespaced units. They're the answer to the v2.10 split: ansible-core ships the engine and a small built-in module set; everything else lives in collections distributed via Ansible Galaxy or Automation Hub.

What's in a collection

A collection on disk has this shape:

ansible_collections/
  <namespace>/
    <collection_name>/
      MANIFEST.json           # Galaxy metadata (auto-generated at build)
      FILES.json              # Per-file checksums (auto-generated at build)
      galaxy.yml              # Source-of-truth metadata
      meta/
        runtime.yml           # Plugin redirects, action_groups, requires_ansible
      plugins/
        action/
        become/
        callback/
        cache/
        connection/
        filter/
        inventory/
        lookup/
        modules/
        module_utils/
        strategy/
        test/
        vars/
        ...
      roles/
        <role_name>/
          tasks/
          handlers/
          defaults/
          vars/
          meta/
      playbooks/
      tests/
      docs/

The relevant Python entry point is ansible_collections.<namespace>.<collection_name>, exposed as a normal Python package by the collection loader.

How ansible-galaxy collection install works

graph TD
    USER[ansible-galaxy collection install ns.col] --> CLI[GalaxyCLI<br/>lib/ansible/cli/galaxy.py]
    CLI --> API[GalaxyAPI<br/>lib/ansible/galaxy/api.py]
    API --> SERVER[Galaxy server / Automation Hub]
    SERVER --> META[Per-version metadata]
    META --> RESOLVE[resolvelib dependency<br/>lib/ansible/galaxy/dependency_resolution]
    RESOLVE --> PLAN[Install plan: list of versions]
    PLAN --> DOWNLOAD[Download tarballs]
    DOWNLOAD --> ART[ConcreteArtifactsManager<br/>lib/ansible/galaxy/collection/concrete_artifact_manager.py]
    ART --> EXTRACT[Extract to COLLECTIONS_PATH]
    EXTRACT --> SIG[Optional: GPG verify<br/>lib/ansible/galaxy/collection/gpg.py]

Files involved:

File	Lines	Purpose
lib/ansible/cli/galaxy.py	1,889	CLI dispatch — install/build/publish/list/info/init for both roles and collections
lib/ansible/galaxy/api.py	38,985	Talks to the Galaxy v3 REST API; pagination, auth, retry
lib/ansible/galaxy/collection/__init__.py	1,933	Top-level install/build/verify orchestration
lib/ansible/galaxy/collection/concrete_artifact_manager.py	(large)	Holds downloaded tarballs, extracts them, integrity-checks
lib/ansible/galaxy/collection/gpg.py	(medium)	GPG signature verification
lib/ansible/galaxy/dependency_resolution/	(multiple)	The resolvelib-based provider/reporter
lib/ansible/galaxy/data/	(data)	Skeletons for ansible-galaxy init
lib/ansible/galaxy/token.py	6,780	Galaxy authentication token storage
lib/ansible/galaxy/role.py	19,693	Pre-collection roles support (ansible-galaxy role install)

Resolving collection plugins at runtime

When a play references community.general.archive, the action loader (in lib/ansible/plugins/loader.py) parses the FQCN, asks the collection loader for the file path, and imports it.

The collection's meta/runtime.yml can include:

• plugin_routing: — redirects from one plugin name to another, with deprecation/removal metadata. The loader honors these in the same way it honors lib/ansible/config/ansible_builtin_runtime.yml.
• action_groups: — named collections of related modules used by module_defaults (e.g., all ec2_* modules form an aws action group).
• requires_ansible: — minimum ansible-core version. Validated at plugin-load time.
• import_redirection: — redirect a module_utils import path to another collection.

The role of ansible.builtin and ansible.legacy

Two synthetic collections have special meaning:

• ansible.builtin — the modules and plugins that ship with ansible-core. ansible.builtin.copy is the same as lib/ansible/modules/copy.py. The collection has no on-disk root; the loader synthesizes it.
• ansible.legacy — a "what would happen pre-collections" name for the same content, but with one important quirk: bare names like copy resolve to ansible.legacy.copy, and ansible.legacy includes user-supplied modules under library/ next to the playbook. So a custom library/copy.py shadows ansible.builtin.copy only via the legacy resolution path.

lib/ansible/config/ansible_builtin_runtime.yml is mostly a giant table of <short_name>: redirect: <fqcn> entries describing how the v2.10 split mapped each module/plugin to its new home.

Building and publishing

ansible-galaxy collection init namespace.name      # scaffold a new collection
ansible-galaxy collection build                    # produce a .tar.gz with MANIFEST.json + FILES.json
ansible-galaxy collection publish ns-name-1.0.0.tar.gz   # push to Galaxy

build walks the source tree, applies build_ignore patterns from galaxy.yml, computes per-file checksums, generates MANIFEST.json from the galaxy.yml metadata, and emits a tarball.

Dependency resolution

ansible-galaxy collection install uses resolvelib (declared in requirements.txt as resolvelib >= 0.8.0, < 2.0.0). Each collection's metadata declares its dependencies as dependencies: {ns.col: ">=1.0.0,<2.0.0"} in galaxy.yml. resolvelib's provider/reporter abstractions are implemented in lib/ansible/galaxy/dependency_resolution/. The result is a flat list of version-pinned collections to install.

The version comparator follows PEP 440 / packaging.version.Version semantics, with * shorthand also accepted.

Where collections are installed

COLLECTIONS_PATHS (default ~/.ansible/collections:/usr/share/ansible/collections) lists the directories the loader searches. The first writeable entry is also the install destination unless --collections-path overrides.

A collection installed at ~/.ansible/collections/ansible_collections/community/general/ is importable as ansible_collections.community.general from any Python process the controller spawns.

requirements.yml

Like a pip requirements file, but for collections:

collections:
  - name: community.general
    version: '>=8.0.0,<9.0.0'
  - name: ansible.posix
  - name: my.private
    source: https://hub.example.com/api/galaxy/
    type: galaxy

Plus role requirements (legacy):

roles:
  - name: geerlingguy.docker

ansible-galaxy collection install -r requirements.yml reads the file and installs everything; ansible-galaxy install -r requirements.yml does both roles and collections.

Signature verification

Optional GPG signature verification is implemented in lib/ansible/galaxy/collection/gpg.py. When configured (GALAXY_REQUIRE_VALID_SIGNATURES=true), each collection tarball must come with valid signatures from a configured keyring.

Integration points

• Imported by: lib/ansible/cli/galaxy.py (the CLI), the plugin loader at runtime.
• Imports: requirements.txt deps (resolvelib, cryptography for hashes, packaging for version specifiers), the collection loader.
• Talks to: Galaxy's v3 REST API (or Automation Hub, or a private mirror) over HTTPS.

Entry points for modification

• CLI changes — lib/ansible/cli/galaxy.py. The 1,889-line file has clearly-named subcommand methods.
• API client changes — lib/ansible/galaxy/api.py. Pagination, retry, auth headers.
• Resolver changes — lib/ansible/galaxy/dependency_resolution/. resolvelib gives you the algorithm; the provider supplies metadata.
• Format changes (e.g., a new MANIFEST/FILES version) — lib/ansible/galaxy/collection/__init__.py:_consume_indicated_artifact and _build_collection_tar.

Cross-links

• Systems → Plugin loader — the runtime resolution side.
• Apps → ansible-galaxy — the user-facing CLI.
• Reference → Configuration — COLLECTIONS_PATHS, GALAXY_* options.