The ansible-galaxy install command can be used to:

• Install a role
• Install a collection

Let's say you want to install the bertvv.httpd role, which can be found at the Ansible Galaxy website or you could use the ansible-galaxy search command to find the role to install and the ansible-galaxy info command to display more information about the role.

Here is what the install command should produce.

ansible-galaxy install bertvv.httpd
. . .
- downloading role 'httpd', owned by bertvv
- downloading role from https://github.com/bertvv/ansible-role-httpd/archive/v2.0.0.tar.gz
- extracting bertvv.httpd to /etc/ansible/roles/bertvv.httpd
- extracting bertvv.httpd to /usr/local/ansible/roles/bertvv.httpd
- bertvv.httpd (v2.0.0) was installed successfully

API Server

By default, the ansible-galaxy command will connect to https://galaxy.ansible.com. If you have your own internal Galaxy server, the -s or --server option can be used to point to your own internal Galaxy server.

ansible-galaxy install bertvv.httpd --server http://galaxy.example.com

Roles file

A YAML file can be used to download and install a role. Usually the file is named requirements.yml. Here is what you would put in the requirements.yml file to download and install the bertvv.httpd role from the Ansible Galaxy website.

- name: bertvv.httpd

The -r or --role-file option would then be used to install the roles listed in the YAML file.

ansible-galaxy install --role-file requirements.yml

If the role is successfully installed, something like this should be returned.

- extracting bertvv.httpd to /home/john.doe/.ansible/roles/foo
- bertvv.httpd was installed successfully

Optionally, a specific version of a role can be specified.

- name: bertvv.httpd
  version: v1.3.0

Optionally, you can specify where the role should be downloaded from, such as from github.com instead of galaxy.ansible.com. When "scm" (Secure Content Management) is not include, scm will default to git, thus there isn't a need to include scm when the source is Git.

- src: https://github.com/bennojoy/nginx
  scm: git
  name: nginx

However, if the source is BitBucket, then scm must be set to hg.

- src: http://bitbucket.org/willthames/hg-ansible-galaxy
  scm: hg

Or you can download a TAR archive of a role from a web server.

- src: http://www.example.com/foo.tar
  name: foo

Roles path

Notice in the output above that there was an attempt to first extract the role to the /etc/ansible/roles directory, and then to the /usr/local/ansible/roles directory. Let's say your ansible.cfg file has the following.

With this configuration, the role will be extracted to the first directory that exists in roles_path. For example, if /etc/ansible/roles exists, the role would be extracted to /etc/ansible/roles. If /etc/ansible/roles does not exist, then the role will be extracted to /usr/local/ansible/roles.

roles_path    = /etc/ansible/roles:/usr/local/ansible/roles

Or, the -p or --roles-path option can be used to specify where the role should be extracted to.

ansible-galaxy install bertvv.httpd --roles-path /usr/local/ansible/roles