thoughtbot/laptop: a macOS setup script for web and mobile developers

What thoughtbot/laptop actually solves

A new macOS machine is a blank slate. You install Homebrew, then a shell, then a version manager, then a database, then a language runtime, and somewhere in that sequence a version mismatch appears and you spend an afternoon on it. thoughtbot/laptop exists to collapse that sequence into one script. The README describes it as "a script to set up a macOS laptop for web and mobile development," and the repository reflects that: a single executable file named mac, plus a README, a CHANGELOG, a LICENSE and a SECURITY.md.

The audience is narrow and the README does not pretend otherwise. It supports macOS Tahoe (26.x), Sequoia (15.x), Sonoma (14.x) and Ventura (13.x), on both Apple Silicon and Intel. Older versions may work, but the README says they are not regularly tested. If you run Linux or Windows, this project is not for you at all. If you run a macOS version outside that list, you are on your own.

The other thing it solves is repeatability. The README states the script "can be run multiple times on the same machine safely" and that it "installs, upgrades, or skips packages based on what is already installed." That is the property that makes it useful beyond a one-time bootstrap: you can rerun it after a macOS upgrade, or hand it to a new hire, without wondering whether a second run will break the first.

The mechanism: one shell script, Homebrew as the substrate

There is no daemon, no configuration format and no plugin system. The repository's top level contains a single script, mac, and the README tells contributors to "Edit the mac file." Everything happens in that file, in order, as shell commands.

The data flow is linear. The script checks what is already present, then installs, upgrades or skips each package. Homebrew is the base layer: the README lists it first, "for managing operating system libraries," and everything else is layered on top of it. Above Homebrew sit the Unix tools (fzf, Universal Ctags, Git, OpenSSL, RCM, The Silver Searcher, Tmux, Watchman, Zsh), the Heroku tools (Heroku CLI and Parity), the GitHub CLI, ImageMagick, the language and package managers (asdf-vm, Bundler, Node.js and npm, Ruby stable, Yarn, Rosetta 2), and the databases (Postgres and Redis).

Two details in that list are worth pausing on. First, asdf-vm is the version manager for programming languages, so the script does not pin a single global Ruby or Node version; it installs the manager and leaves version selection to you. Second, Rosetta 2 is installed "for running tools that are not supported in Apple silicon processors," which tells you the script is written for a mixed fleet rather than assuming Apple Silicon only.

The customization hook is the cleanest part of the design. The README says your ~/.laptop.local "is run at the end of the Laptop script." That means your additions execute after the base provisioning, and the README asks you to write them so they can run safely more than once. Helper functions such as fancy_echo and gem_install_or_update are available inside that file, according to the README.

Installing it and running it the first time

The README's install path is deliberately manual, and the order matters. First download the script with curl. The README gives this exact command:

curl --remote-name https://raw.githubusercontent.com/thoughtbot/laptop/main/mac

That writes a file named mac into your current directory. The README then tells you to review it before running it, with the parenthetical "avoid running scripts you haven't read!":

less mac

When you are satisfied, execute it. The README pipes output to a log file so you have a record afterwards:

sh mac 2>&1 | tee ~/laptop.log

The README says the whole thing "should take less than 15 minutes to install (depends on your machine)." When it finishes, you can review the log:

less ~/laptop.log

For your own additions, create ~/.laptop.local. The README's example uses brew bundle with a heredoc to add packages, then defines small shell functions to check whether a Docker machine exists and start it if not, then runs brew cleanup and, if ~/.rcrc exists, rcup. The README's own note is that you should write these customizations so they can be run safely more than once, and points to the mac script for examples. If you use thoughtbot's dotfiles, the README links to a separate install page for those; they are optional.

Where it stops being the right tool

The supported macOS list is the first hard boundary. Four versions are named, and the README is explicit that older versions may work but are not regularly tested. On a machine running something older, you are running an untested path, and the README only says bug reports are welcome; it does not promise a fix.

The second boundary is the tool list itself. The script installs Ruby stable, Node.js, Yarn, Postgres and Redis, alongside Heroku CLI and Parity. If your stack is Go, Rust or Python, the script still installs a Ruby and Node toolchain you did not ask for. The README points you at ~/.laptop.local for additions, and the example there adds go, ngrok and watch, but there is no documented mechanism for removing what the base script installs. You are extending a prescribed set, not composing your own from scratch.

The third is the trust model. The script is downloaded over curl and run with sh. The README's own mitigation is to read the file first with less, which is honest advice rather than a security control. There is no checksum, no signature and no version pinning described in the README. You are trusting whatever is at the main branch at the moment you fetch it.

Finally, the log. Debugging is manual: the README says your last run is saved to ~/laptop.log, that you should read through it to debug yourself, and that if you cannot, you should copy the failing lines into a new GitHub Issue or attach the whole log. There is no rollback procedure documented in the README.

How it compares to a Brewfile or a dotfiles manager alone

The closest alternative is a hand-written Brewfile driven by brew bundle. That approach is more granular: you declare exactly which formulae and casks you want, and Homebrew handles installation and upgrades. What it does not give you is the imperative layer. thoughtbot/laptop does more than install packages; it sets Zsh as your shell, installs Rosetta 2, and provides shell functions in the script that your ~/.laptop.local can call. A Brewfile cannot express "start the default Docker machine if it is not running."

The second alternative is a dotfiles manager such as RCM, which the script itself installs "for managing company and personal dotfiles." RCM and thoughtbot/laptop are complementary rather than competing: the README's own customization example checks for ~/.rcrc and runs rcup at the end. If your problem is keeping shell configuration in sync across machines, RCM addresses that. If your problem is that a fresh machine has no tools at all, RCM does not help until the tools exist.

The honest comparison is that thoughtbot/laptop is a bundled opinion. You get a coherent, tested combination of tools for web and mobile work on macOS, and you give up fine-grained control over what lands on the disk. A Brewfile is the better choice if your team's toolset diverges sharply from thoughtbot's, or if you need the same provisioning story on Linux.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-08-13, which is recent enough that the project is being touched. The release history is uneven, though. There are releases dated 2026-08-13, 2024-09-24 and 2023-10-03, so a roughly annual cadence with a long gap in the middle is the pattern the release list shows. Plan for the possibility that a macOS point release lands before the script is updated for it.

The upgrade cost is low by design. Because the script installs, upgrades or skips based on what is already present, and because the README states it can be rerun safely, the upgrade path is to download the current mac file and run it again. Your ~/.laptop.local runs at the end, so your customizations survive that rerun as long as you followed the README's advice to make them idempotent. The CHANGELOG is the file to read before rerunning, since the README asks contributors to update it.

The licence is MIT. The README states the project is "free software, and may be redistributed under the terms specified in the LICENSE file," and the copyright line names thoughtbot, inc. starting in 2011. MIT is permissive, so redistribution and modification are allowed with the licence and copyright notice retained. That is a description of the licence text, not legal advice; if you are vendoring the script into a commercial product or an internal platform, have your own counsel read the LICENSE file rather than relying on a summary. One separate point: the README's footer states that the names and logos for thoughtbot are trademarks, which is a different question from the code licence.

Editorial conclusion

Adopt thoughtbot/laptop if you are setting up a macOS machine for web or mobile development and you want the same toolset across a team. Skip it if you need Linux or Windows, or if you are not willing to read a shell script before running it. Before you commit, verify three things: that your macOS version is one of the four listed in the README, that the tool list matches your stack, and that you have a place to put your own additions in ~/.laptop.local. The script writes a log to ~/laptop.log, so if something fails, that file is the first place to look.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. thoughtbot/laptop on GitHub