How To: Install Ansible on OSX

Ansible is an orchestration engine that automates configuration management and application deployment.

Ansible uses YAML, in the form of Ansible playbooks, to describe automation jobs and SSH to communicate with the systems it manages.


  • Xcode Command Line Tools

To install the Xcode Command Line Tools in OSX Mavericks (10.9.x), enter the following command:

sudo xcode-select --install

To check that they have been installed, enter the following command::

sudo xcode-select -p

If you see:


Then you're good to go.

Install Ansible

To install Ansible on OSX you should use "pip" the Python package manager:

sudo easy_install pip

First, we need to install the Python Cryptography Toolkit:

sudo ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install pycrypto

Note: sudo filters out most environment variables as a security measure.

Now, we can install Ansible:

sudo pip install ansible

Finally, to check that Ansible has been installed, enter the following command:

sudo pip install ansible --upgrade

Configure Ansible

By default, Ansible uses SSH to communicate with remote systems, so you should be familiar with key-based authentication and SSH configuration.

Inventory Files

Ansible uses inventory files to describe the systems it manages.

To create an inventory file, enter the following commands:

mkdir ~/ansible
touch ~/ansible/hosts

Open it with a text editor. I used TextEdit:

open -a TextEdit ~/ansible/hosts

And, update it as follows:

[production] ansible_connection=ssh ansible_ssh_user=homer

Note: For each server you want to manage there should be a corresponding entry in your ~/.ssh/known_hosts file.

We also need to let Ansible know where it can find our inventory file, add the following line to the end of your ~/.bash_profile (or if you don't want to maintain two separate config files for login and non-login shells, put your common settings in ~/.bashrc and make sure you source it from your ~/.bash_profile):

export ANSIBLE_HOSTS=~/ansible/hosts

Load the changes into your current shell:

source ~/.bash_profile

Now, we can use the ping module to test Ansible:

ansible -m ping

You should then see output like: | success >> {
    "changed": false, 
    "ping": "pong"

To run Ansible from the command line, you need to provide a host pattern (e.g., a server name:; or a group name: production) and the name of the module (-m MODULE_NAME) you want to invoke.

Now, try the setup module which gathers data about remote systems, and then returns those values:

ansible -m setup

You can use ansible-doc to obtain a list of Ansible modules:

ansible-doc -l

And, to learn more about a particular module:

ansible-doc setup

What's Next

In the next post, we'll take a look at Ansible commands and playbooks.