AnsibleByExample

Install Ansible on macOS — Homebrew

Beginneransiblebrewdeveloperdevops
2024-01-014By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

Introduction

Homebrew is the easiest way to install Ansible on macOS — it handles all dependencies automatically and works on both Intel and Apple Silicon (M1/M2/M3/M4) Macs.

Install Homebrew

If you don't have Homebrew yet:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Ansible

brew install ansible

Sample output (Apple Silicon):

==> Downloading https://ghcr.io/v2/homebrew/core/ansible/manifests/9.2.0
==> Pouring ansible--9.2.0.arm64_sonoma.bottle.tar.gz
🍺  /opt/homebrew/Cellar/ansible/9.2.0: 28,126 files, 350MB

Verify Installation

ansible --version

ansible [core 2.16.3]
  config file = None
  configured module search path = ['/Users/you/.ansible/plugins/modules']
  ansible python module location = /opt/homebrew/lib/python3.12/site-packages/ansible
  python version = 3.12.2
  jinja version = 3.1.3

Update Ansible

brew upgrade ansible

Method 2: pip (Python Package Manager)

Using a Virtual Environment (Best Practice)

# Create virtual environment
python3 -m venv ~/ansible-venv

# Activate it
source ~/ansible-venv/bin/activate

# Install Ansible
pip install ansible

# Verify
ansible --version

Install Specific Version

pip install ansible==9.2.0

# Or install only ansible-core (lighter)
pip install ansible-core==2.16.3

Install ansible-core Only

If you only need the core engine without extra collections:

pip install ansible-core
PackageIncludesSize
ansibleansible-core + 85+ collections~350 MB
ansible-coreCore engine only~15 MB

Method 3: pipx (Isolated Install)

# Install pipx
brew install pipx
pipx ensurepath

# Install Ansible in isolated environment
pipx install ansible --include-deps

# Verify
ansible --version

pipx keeps Ansible in its own isolated Python environment, avoiding dependency conflicts.

Post-Installation Setup

Create Configuration File

mkdir -p ~/.ansible
cat > ~/.ansible.cfg << 'EOF'
[defaults]
inventory = ~/ansible/inventory
remote_user = ansible
host_key_checking = False
retry_files_enabled = False
stdout_callback = yaml

[privilege_escalation]
become = True
become_method = sudo
become_ask_pass = False
EOF

Create Inventory File

mkdir -p ~/ansible
cat > ~/ansible/inventory << 'EOF'
[local]
localhost ansible_connection=local

[servers]
# Add your servers here
# web01.example.com
# db01.example.com
EOF

Test Ansible

# Test local connection
ansible localhost -m ping

# Expected output:
# localhost | SUCCESS => {
#     "changed": false,
#     "ping": "pong"
# }

# Run a simple command
ansible localhost -m command -a "uname -a"

Install Additional Collections

# Install popular collections
ansible-galaxy collection install community.general
ansible-galaxy collection install ansible.posix
ansible-galaxy collection install community.docker

# List installed collections
ansible-galaxy collection list

Troubleshooting

"command not found: ansible"

Homebrew on Apple Silicon installs to /opt/homebrew/bin/. Ensure it's in your PATH:

# Add to ~/.zshrc
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Python Version Conflicts

macOS ships with a system Python. Ansible needs Python 3.9+:

# Check Python version
python3 --version

# Install Python via Homebrew if needed
brew install python@3.12

SSL Certificate Errors

# Install/update certificates
pip install --upgrade certifi

# Or set the cert path
export SSL_CERT_FILE=$(python3 -c "import certifi; print(certifi.where())")

Slow Homebrew Install

# Update Homebrew first
brew update

# Clean up old versions
brew cleanup

Permission Errors with pip

Never use sudo pip install. Use a virtual environment or pipx instead:

# WRONG
sudo pip install ansible

# CORRECT
python3 -m venv ~/ansible-venv
source ~/ansible-venv/bin/activate
pip install ansible

macOS-Specific Tips

SSH Key Setup

# Generate SSH key (if you don't have one)
ssh-keygen -t ed25519 -C "your_email@example.com"

# Copy to remote servers
ssh-copy-id user@server.example.com

Connect to Remote Linux Hosts

# test-playbook.yml
---
- name: Test remote connection
  hosts: servers
  tasks:
    - name: Gather facts
      ansible.builtin.setup:
        gather_subset: min

    - name: Show OS info
      ansible.builtin.debug:
        msg: "{{ ansible_distribution }} {{ ansible_distribution_version }}"

ansible-playbook test-playbook.yml

Conclusion

brew install ansible is the fastest way to get Ansible running on macOS — it works on both Intel and Apple Silicon with zero manual dependency management. For more control, use pip in a virtual environment or pipx for isolation. After installation, create an ~/.ansible.cfg, set up your inventory, and test with ansible localhost -m ping. You're ready to automate.

All Tutorials