ansible-galaxy
Manage Ansible roles and collections
TLDR
List installed roles or collections
Search for a role with various levels of verbosely (-v should be specified at the end)
Install or remove role(s)
Create a new role
Get information about a role
Install or remove collection(s)
Display help about roles or collections
SYNOPSIS
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
PARAMETERS
--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').
DESCRIPTION
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.
CAVEATS
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.
ROLE VS. COLLECTION MANAGEMENT
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.
REQUIREMENTS FILE
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).
OFFLINE INSTALLATION
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.
CUSTOM PATHS
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.
HISTORY
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.
SEE ALSO
ansible(1), ansible-playbook(1), ansible-vault(1), ansible-test(1)