What is mac-dev-playbook?

geerlingguy/mac-dev-playbook — explained in plain English

Analysis updated 2026-06-24

★ 6,965ShellAudience · developerComplexity · 3/5Setup · moderate

Mindmap

mindmap
  root((repo))
    What it does
      Automate Mac setup
      Install dev tools
      Apply system prefs
    Tech Stack
      Ansible playbook
      Shell scripts
      macOS
    What Gets Installed
      CLI tools
      Desktop apps
      Dotfiles config
    Use Cases
      New Mac setup
      Remote Mac setup
      Repeatable config

mindmap root((repo)) What it does Automate Mac setup Install dev tools Apply system prefs Tech Stack Ansible playbook Shell scripts macOS What Gets Installed CLI tools Desktop apps Dotfiles config Use Cases New Mac setup Remote Mac setup Repeatable config

Click or tap to explore — scroll the page freely

What do people build with it?

USE CASE 1

Set up a brand new Mac with all your developer tools and apps automatically by running a single command.

USE CASE 2

Fork the playbook and customize it to create your own repeatable Mac setup you can reuse after every reinstall.

USE CASE 3

Provision a remote macOS machine over SSH with a consistent developer environment without sitting at the machine.

USE CASE 4

Keep your Mac tools and settings versioned in git so you can track what changed over time.

What is it built with?

AnsibleShellPythonmacOS

How does it compare?

	geerlingguy/mac-dev-playbook	git-quick-stats/git-quick-stats	oracle/docker-images
Stars	6,965	6,972	6,972
Language	Shell	Shell	Shell
Setup difficulty	moderate	easy	hard
Complexity	3/5	1/5	3/5
Audience	developer	developer	ops devops

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

Requires installing Ansible before running, defaults are the author's personal config and need customization to match your own preferences.

License not specified in the explanation.

So what is it?

This repository contains an automated Mac setup script that installs and configures a developer's tools and applications in one pass. The author, a web and software developer, uses it to get a new or wiped Mac ready for work without manually installing and tweaking dozens of programs one by one. The automation is built on Ansible, a tool that lets you describe what software and settings a computer should have, then applies those descriptions to reach that state. You run a handful of commands to get Ansible set up, then a single command runs the playbook and handles the rest. It installs command-line tools, desktop applications, programming language runtimes, and system preferences. The default setup includes common developer applications like Docker, Slack, Google Chrome, Firefox, and Sublime Text, along with a long list of command-line tools such as Git, Go, Node, PHP, and various networking utilities. It also applies the author's personal configuration files, known as dotfiles, and configures macOS system settings. All of these defaults can be overridden: you create a personal configuration file and list only the packages and apps you want, without modifying the main playbook. The playbook can also be pointed at a remote Mac over SSH, not just the machine you are sitting at. That makes it usable for setting up a cloud-hosted Mac or another machine on your network. The repository is one person's personal setup, shared publicly so others can fork it and adapt it to their own needs. The README includes a detailed from-scratch setup guide for those who want a complete reference. The project is tested automatically on GitHub Actions using real macOS infrastructure, so changes can be verified without wiping a physical machine.

Copy-paste prompts

Prompt 1

Help me fork geerlingguy/mac-dev-playbook and change the defaults to install VS Code, iTerm2, Python, and Node.js instead of the author's preferred apps.

Prompt 2

I want to add my own dotfiles to the mac-dev-playbook setup. Show me how to point the playbook at my dotfiles repository.

Prompt 3

Walk me through running geerlingguy/mac-dev-playbook on a fresh Mac from scratch, including installing Ansible before the playbook runs.

Prompt 4

How do I add a new Homebrew cask like Figma to the mac-dev-playbook and verify it with GitHub Actions before running it on my machine?

Prompt 5

I want to use mac-dev-playbook to provision a remote Mac mini over SSH. What configuration changes do I need to make?

Frequently asked questions