Ansible is a powerful devops/automation tool that helps you control fleets of servers and their applications with ease.
This post covers installing ansible on MacOS using the installation method recommended by the project: pip, the python package manager. There are a few other ways to install ansible on MacOS, including with the brew package manager.
This post assumes that you are interested in installing ansible only for the current user only. If you require a system-wide/multi-user installation, skip to Step 8 to learn more about the MacOS System Integrity Protection (SIP) feature before proceeding.
Installing Ansible with pip
You may be able to skip steps 1, 2, and/or 3 if you already have XCode, XCode Command Line Tools, and/or pip installed on your system.
Step 1: install XCode
Most developers already have XCode installed. If you’re not sure, you can look for it in the Applications folder on your Mac.
XCode is available for free on the App Store. It can be helpful to run XCode at least once after installing it to help it complete its installation process, and get you to agree to any license terms.
The following steps will fail if you have not agreed to Xcode’s license terms.
Step 2: install XCode command line tools
The XCode command line tools include compilers and other tools necessary to proceed. In the MacOS Terminal app, run the command:
If this is a fresh install, you will be prompted to agree to Apple’s terms for the command line tools. After you consent, they will download and install.
If you already have the command-line tools installed. The script will let you know and exit.
Once the XCode command line tools are installed, you can use development tools like the gcc compiler. For example, you should be able to run the following command and successfully receive gcc’s version information as output:
If everything looks good and the above command does not throw an error, proceed to the next step.
Step 3: install pip
MacOS comes pre-installed with python, but not pip. To install it, input the following into the Terminal app:
sudo easy_install pip
There is no harm to running this command in cases where pip is already installed.
Step 4: install ansible
To install ansible system-wide, run the following command:
sudo pip install ansible
If you prefer a local install within your user account, you can remove the ‘sudo’ and add the
--user flag to the above.
After the installation process has completed, you can verify the install was a success by executing a basic command like:
ansible --version. It should run without error.
Step 5: create /etc/ansible
Ansible looks for default configuration files in /etc/ansible. This directory is unlikely to exist on your machine. The following command will create this folder if it doesn’t already exist:
sudo mkdir -p /etc/ansible
Step 6: install optional/helpful packages
It can be helpful to install the python passlib library because MacOS doesn’t use the same types of password hashes as linux does, and you are likely going to want to manage linux machines with ansible. Passlib provides a common and consistent hash generator across operating systems.
To install passlib globally on your Mac:
sudo pip install passlib
If you installed ansible locally, you can use the command
pip install --user passlib instead.
Step 7: test out your installation
Per above, if the install was successful, you can now use the ansible command from the Terminal:
A “hello world” of sorts for ansible is pinging yourself:
ansible localhost -m ping
You can also try running an arbitrary command on yourself (such as
uname -a or
ansible localhost -a 'uname -a'
To get ansible to detect facts about your machine, try the following. Note the filter argument: it restricts what is returned so you don’t get BLASTED with facts.
By default ansible gathers almost everything there is to know about its target machines and populates them into variables that you can then use in your tasks, roles, and plays. As you learn ansible, you’ll discover this is incredibly useful. Ansible users can customize this behaviour and optionally turn it off to realize performance gains when it isn’t required. For now though, you’re just getting started:
ansible localhost -m setup -a 'filter=ansible_distribution'
Step 8: upgrade ansible
It can be a good idea to upgrade ansible right off the bat to ensure that everything is current, and to understand how the MacOS System Integrity Protection (SIP) feature impacts your installation:
sudo pip install ansible --upgrade
If this command partially runs and then produces an error, it is because of the SIP feature, originally introduced in OSX El Capitan. You can work around that by adding the
--user python parameter to the above command. With this argument, upgrades will be installed for the current user only vs. system-wide, and the upgrade will succeed. The revised command:
sudo pip install ansible --upgrade --user python
Understanding MacOS’ System Integrity Protection (SIP) Feature
SIP was introduced in OSX El Capitan and prevents certain system files, such as those associated with MacOS-bundled python, from being clobbered by anyone — including root.
To avoid SIP-related issues on a system-wide install, you may want to consider using a different python than the one bundled with MacOS. Using a python virtualenv is one option. Another option for multi-user systems is to install user-specific copies of python + pip + ansible within each appropriate user account (e.g. via brew package manager for MacOS).
A more thorough discussion of issues regarding the use of pip on MacOS systems with SIP can be found here:
Step 9: get started!
Congratulations! You have installed ansible on MacOS!
If you’re new to ansible, check out the documentation at http://docs.ansible.com/ansible/latest/index.html to get started!