ansible-galaxy

List installed roles or collections

$ ansible-galaxy [role|collection] list

$ ansible-galaxy role search [keyword] -v[vvvvv]

$ ansible-galaxy role [install|remove] [role_name1 role_name2 ...]

$ ansible-galaxy role init [role_name]

$ ansible-galaxy role info [role_name]

$ ansible-galaxy collection [install|remove] [collection_name1 collection_name2 ...]

$ ansible-galaxy [role|collection] [[-h|--help]]

ansible-galaxy [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND_OPTIONS] [ARGUMENTS]

Commands:
  install            Install roles or collections from Galaxy or a local path.
                  e.g., ansible-galaxy install author.role_name
                  e.g., ansible-galaxy install author-collection_name
  init               Create a new role skeleton.
                  e.g., ansible-galaxy init my_new_role
  list               List installed roles or collections.
  remove            Remove an installed role.
                  e.g., ansible-galaxy remove author.role_name
  search            Search Galaxy for roles or collections.
                  e.g., ansible-galaxy search webserver
  login             Authenticate to a Galaxy server.
  logout            Log out from a Galaxy server.
  collection        Manage collections (subcommands: build, init, install, publish, verify).
                  e.g., ansible-galaxy collection build

--help, -h
    Show the help message and exit.

--version
    Show program's version number and exit.

--verbose, -v
    Enable verbose output. Use multiple times for more verbosity (-vvv).

--force
    Force overwriting an existing role or collection when installing.

--no-deps
    Do not download dependencies when installing a role or collection.

--role-file, -r
    Path to a file containing a list of roles or collections to install (requirements.yml).

--roles-path
    The path to the directory where roles should be installed. Defaults to ~/.ansible/roles or current working directory.

--collections-path
    The path to the directory where collections should be installed. Defaults to ~/.ansible/collections.

--ignore-certs
    Ignore SSL certificate validation errors when connecting to Galaxy.

--server
    The Galaxy API server URL to use (e.g., https://galaxy.ansible.com).

--token
    Authentication token for the Galaxy API server. Can be stored with 'login'.

--timeout
    Set the socket timeout in seconds for network operations.

--offline
    Do not connect to the Galaxy server. Only use local cache and paths (useful for 'list' command).

--format
    Output format for 'list' or 'search' commands (e.g., 'json', 'yaml').

The ansible-galaxy command is a command-line utility used to interact with Ansible Galaxy, a free website for finding, reusing, and sharing Ansible content, primarily roles and collections.

It serves as the primary tool for installing community-contributed roles and collections from Galaxy into your Ansible project. This significantly promotes reusability and standardization in Ansible automation. Beyond installation, ansible-galaxy allows users to initialize new role or collection structures, list installed content, remove existing content, and search the Galaxy platform directly from the terminal.

With the introduction of Ansible Collections in Ansible 2.9, ansible-galaxy was extended to support these new packaging formats, enabling users to build, initialize, and install collections, which encapsulate not only roles but also modules, plugins, playbooks, and documentation. It's an indispensable tool for anyone building, consuming, or contributing to the Ansible ecosystem, streamlining the process of managing dependencies and leveraging community-driven content.

When installing roles or collections, ansible-galaxy often requires network connectivity to reach the Ansible Galaxy server. For private or air-gapped environments, content must be pre-downloaded or served from a private Galaxy instance.

Using the --force option can overwrite existing content, potentially leading to unintended changes if not used carefully.

Dependencies specified in meta/main.yml for roles or galaxy.yml for collections are automatically resolved and installed by default, which can sometimes pull in many additional components. Use --no-deps to prevent this behavior.

Content from Ansible Galaxy is community-contributed; it's advisable to review roles and collections before deploying them in production environments to ensure security and quality standards are met.

Originally, ansible-galaxy primarily managed Ansible Roles. With Ansible 2.9+, it also manages Ansible Collections. The syntax for installation using `ansible-galaxy install` handles both (e.g., `author.role_name` or `author.collection_name`). However, specific `collection` subcommands (e.g., `ansible-galaxy collection build`) are exclusively for collections, and `ansible-galaxy init` (without `collection`) is for roles.

For managing multiple roles or collections, it's common practice to use a requirements.yml file. This YAML file lists roles or collections with their sources (Galaxy, Git, local path) and versions. You can install all listed dependencies using `ansible-galaxy install -r requirements.yml` (for roles) or `ansible-galaxy collection install -r requirements.yml` (for collections, if specified in a collection-specific requirements file).

If direct internet access to Galaxy is not available, you can use ansible-galaxy to install roles/collections from a local tarball (e.g., `ansible-galaxy install ./my_role.tar.gz`) or from a private Galaxy instance by specifying the --server option.

By default, roles are installed in `~/.ansible/roles` and collections in `~/.ansible/collections/ansible_collections`. These paths can be overridden globally in `ansible.cfg` or per-command using the --roles-path or --collections-path options, allowing for project-specific dependencies or system-wide installations.

The ansible-galaxy command was introduced early in Ansible's development lifecycle to facilitate sharing and reusing Ansible roles. It was initially designed primarily for managing roles on galaxy.ansible.com.

With the release of Ansible 2.9, a significant architectural change introduced Ansible Collections, a new packaging format that allows bundling modules, plugins, roles, playbooks, and documentation together. Consequently, ansible-galaxy was updated to support collections, gaining new subcommands like collection build, collection init, and collection install to manage this new content type. This evolution reflects Ansible's growth towards more modular and organized content distribution.

ansible(1), ansible-playbook(1), ansible-vault(1), ansible-test(1)