The macOS Setup Guide
A complete, opinionated, deeply researched guide to setting up a Mac for computer science students, software engineers, and anyone who uses a Mac as their daily machine. From which Mac to buy, through the first boot, to a fully tuned development environment, security posture, backup strategy and automation layer — with the reasoning behind every recommendation.
macOS 26 Tahoe & 27 Golden Gate
Apple silicon (M1 → M6)
Homebrew 6
Reviewed September 2026
23 chapters + 5 appendices · ~70,000 words · fully scriptable
Who this is for#
- CS students starting a degree (or a bootcamp) who just got a Mac and want to set it up once, properly, without cargo-culting a random dotfiles repo.
- Software engineers joining a new job or replacing a laptop who want a reproducible, secure, fast environment on day one.
- Daily drivers — people who live on their Mac for writing, research, media, school and life — who want the machine to get out of their way.
You don't need to read it front to back. Each chapter stands alone, and the checklists at the end compress the whole thing into a few printable pages.
How to use this guide#
- In a hurry? Read Chapter 2 (first boot), run the bootstrap script, then skim the checklists.
- Buying a Mac? Start with Chapter 1; it is written for September 2026 pricing and the M5/M6 lineup.
- Already set up but it feels messy? Jump to Homebrew, Terminal & shell, Dotfiles and Security.
- Setting up for a specific stack? Languages & runtimes, Containers & VMs and Databases & local dev are self-contained.
Conventions used throughout:
| Convention | Meaning |
|---|---|
| ⌘ ⌥ ⌃ ⇧ fn/🌐 | Command, Option, Control, Shift, Function/Globe |
System Settings → General → Software Update | Navigate the Settings app in that order |
$ command | Run in a terminal; the $ is a prompt, don't type it (the copy button strips it) |
| Recommended / Alternative / | Our default pick / a fine substitute / something we actively steer you away from |
| Note / Tip / Warning callouts | Read these; they save hours |
Every recommendation comes with a why. If you disagree with the why, you'll know exactly what to swap.
What's new in 2026 (and why this guide exists)#
The Mac platform changed more in 2025–2026 than in the previous five years combined, and most setup guides on the internet haven't caught up:
- macOS 27 "Golden Gate" ships September 14, 2026 and is Apple-silicon only. Intel Macs stay on macOS 26 Tahoe (security updates until ~2029). Rosetta 2 is removed for general apps in macOS 28 (fall 2027) — so this guide is uncompromisingly arm64-native first.
- The lineup is completely new: MacBook Neo ($599, A18 Pro, 8 GB), MacBook Air M5, MacBook Pro M5 / M5 Pro / M5 Max, Mac mini M6 and M5 Pro, Mac Studio M5 Max / M5 Ultra, two new Studio Displays. Chapter 1 tells you which one to actually buy.
- Apple shipped its own container runtime (
container, on the Containerization framework) and Docker Desktop is no longer the automatic answer. - Homebrew 6 introduced tap trust, an "ask before install" default, parallel
brew bundle,brew exec, and is dropping Intel bottles this month. - Spotlight became a real launcher (apps, files, actions, clipboard history, Quick Keys) and in Golden Gate hosts Siri AI. The Raycast/Alfred question has a different answer now.
- Security defaults moved: FileVault is on by default at setup, its recovery key lives in iCloud Keychain and the Passwords app, Stolen Device Protection came to MacBooks, Gatekeeper lost its right-click bypass, and encrypted HFS+ backup drives are deprecated.
- Tooling consolidated:
miseanduvreplaced a zoo of version managers; Ghostty matured into the default terminal recommendation; Zed, Cursor and VS Code split the editor market three ways; AI coding agents live in the terminal and in Xcode 27.
Everything below reflects that world. Where a fact is likely to age (a version number, a price), it is dated so you can judge it.
A note on opinions#
This guide is opinionated on purpose. Beginners are paralysed by "it depends"; experts already know when to deviate. So each section gives a default, one or two alternatives, and the reason. When a tool is free for students or free for personal use, we say so, because that matters when you're on a budget.
Nothing here is sponsored. Prices are US list prices at the time of review; education pricing is noted where Apple or a vendor offers it.
Contributing and corrections#
The source is plain Markdown in the guide/ directory of the repository; the site and the single-file GUIDE.md are generated from it by a dependency-free Python script (python3 build.py). Found a mistake, a stale price or a better tool? Open an issue or a pull request.
All chapters
Part I — Before you start
01Hardware & buying guideWhich Mac to buy in late 2026, how much RAM and storage you actually need, education pricing, refurbs, and the accessories that matter.
02First boot, Setup Assistant & migrationSetup Assistant choices that are hard to undo, clean install vs Migration Assistant, the first 30 minutes, and getting to a known-good baseline.
Part II — System & interface
03System Settings, pane by paneA pane-by-pane tour of System Settings in macOS 26/27 with the developer-relevant toggles, the Liquid Glass controls, and the defaults-write equivalents for scripting.
04Finder, Dock & SpotlightFinder as a power tool, Quick Look, the Dock, and the new Spotlight (apps, files, actions, clipboard, Quick Keys) — plus when Raycast or Alfred still earn their place.
05Keyboard, shortcuts & inputModifier remaps, Caps Lock as Control/Escape, Karabiner-Elements, text navigation shortcuts every Mac user should know, input sources, and coming from Windows/Linux keyboards.
06Window management, Spaces & displaysSpaces, Mission Control, native tiling, Stage Manager, and the third-party window managers (Rectangle, Raycast, AeroSpace, yabai) — which one fits how you work, and how to set up multiple displays.
Part III — Developer environment
07Command Line Tools, Xcode & the toolchainCommand Line Tools vs full Xcode, xcode-select, SDKs and simulators, Rosetta 2 and the arm64-only future, and keeping Xcode from eating your disk.
08HomebrewHomebrew 6 from scratch — installing correctly on Apple silicon, formulae vs casks, Brewfiles, tap trust, ask mode, services, maintenance, and the Intel deprecation.
09Terminal & shellChoosing a terminal (Ghostty, iTerm2, WezTerm, Kitty, Warp), zsh configured properly without a framework, Starship, fzf, zoxide, the modern Rust CLI toolkit, tmux, SSH keys, and Touch ID for sudo.
10Dotfiles & GitVersion-controlling your configuration with a bare repo, chezmoi or stow; a complete Git setup for macOS (identity, signing with SSH keys, delta, aliases, global ignore); GitHub CLI; direnv; and secrets hygiene.
11Languages & runtimesOne version manager (mise) for everything, uv for Python, Node/Bun/Deno, Java, Go, Rust, C/C++, Swift, Ruby, .NET, and the ML stack (PyTorch MPS, MLX, Ollama) — with the 2026 release calendar.
12Editors, IDEs & AI coding toolsVS Code, Cursor, Zed, JetBrains, Neovim, Xcode and the AI coding agents — what each is for in 2026, recommended settings, and how to keep the configs in sync across machines.
13Containers & virtual machinesContainers on macOS in 2026 — OrbStack, Docker Desktop, Colima, Podman and Apple's own `container` compared; multi-arch images; Kubernetes locally; Linux and Windows VMs with UTM, Parallels, VMware Fusion and Apple's Virtualization framework.
14Cloud, network & DevOps toolingCloud CLIs and credentials done safely, Terraform/OpenTofu, Kubernetes tooling, API clients, HTTP debugging, Tailscale for reaching your machines, and GitHub Actions locally.
15Databases & local development servicesPostgres, MySQL, SQLite, Redis, MongoDB and friends on a Mac — Homebrew services vs containers vs Postgres.app, GUI clients, local HTTPS and custom domains, and a sane local-dev workflow.
Part IV — Security, backup & maintenance
16Security & privacyA realistic threat model, FileVault and its new recovery-key rules, Gatekeeper and notarisation, the firewall, passwords and passkeys, secrets on disk, permissions hygiene, browser privacy, Lockdown Mode, and what to do when a laptop is lost.
17Backup & recoveryThe 3-2-1 strategy on a Mac — Time Machine done right (encrypted APFS, exclusions), a second local copy, cloud backup, what iCloud is and isn't, testing restores, and recovering a Mac that won't boot.
18Performance & maintenanceKeeping a Mac fast for years — reading Activity Monitor and memory pressure correctly, reclaiming storage (System Data, caches, Docker, Xcode, Homebrew), auditing login items and launch agents, battery health and the 80% charge limit, thermals, Spotlight reindexing, and a low-effort maintenance routine.
Part V — Daily driving & workflows
19Daily-driver appsThe non-developer half of the Mac — browsers, password managers, launchers, clipboard managers, notes, email, calendar, PDF, media, communication, and the utilities that make macOS feel finished. Free/open-source first, with the paid upgrade named where it's worth it.
20CS-student specificWhat's different when the Mac is for a CS degree — free software through student programs, the course-by-course toolchain (C/C++, Java, Python, systems, ML, mobile, databases, theory), running x86 Linux and Windows when a class requires it, remote lab machines, LaTeX/Typst, note-taking, and surviving four years on one battery.
21Automation & scriptingMaking the Mac do things for you — Shortcuts (and running them from the shell), launchd for scheduled and event-driven jobs, Automator's remaining uses, AppleScript and JXA for controlling apps, Hammerspoon for Lua-powered hotkeys and window/system automation, Keyboard Maestro and BetterTouchTool, Folder Actions and Hazel, and a grab-bag of macOS-specific CLI tools every script should know about.
22TroubleshootingA diagnostic playbook for when the Mac misbehaves — the escalation ladder, reading the unified log and crash reports, fixing the classic developer breakages (Homebrew after an OS update, PATH problems, Xcode license, code-signing and Gatekeeper, permissions prompts, DNS, ports in use, Docker), Wi-Fi/Bluetooth/display/audio problems, Recovery mode, Safe Mode, DFU revive, and when a reinstall is actually the answer.
Part VI — Reference
23Checklists & cheat sheetsThe whole guide compressed into printable checklists — the day-one setup order, the 30-minute security pass, the developer-environment checklist, weekly/monthly maintenance, a new-project checklist, a pre-travel checklist, and one-page cheat sheets for the terminal, Homebrew, mise/uv, Git, containers, and macOS CLI tools.
AAppendix A — Bootstrap scriptThe complete, idempotent bootstrap script that turns a fresh Apple-silicon Mac into the setup this guide describes — Command Line Tools, Homebrew, Brewfile, mise/uv, Git and SSH, shell, Touch ID sudo, dotfiles — plus the macOS defaults script, the monthly cleanup script, and the security audit script. Read before running.
BAppendix B — BrewfileThe complete Brewfile behind this guide — 100+ CLI tools, runtimes, container/cloud tooling, fonts, and every GUI app recommended in chapters 9–19, with the optional ones commented out. Plus how Brewfile syntax works, how to keep yours in sync, and how to split it per machine.
CAppendix C — Keyboard shortcutsEvery keyboard shortcut worth knowing on macOS 26/27, grouped by context — system, windows and Spaces, Finder, text editing (including the Emacs bindings that work in every Cocoa text field), screenshots, Spotlight, Safari, Terminal/Ghostty, VS Code, and the modifier symbols decoded.
DAppendix D — GlossaryPlain-English definitions of the macOS, Apple-silicon, and developer-tooling terms used throughout the guide — from APFS and Activation Lock to XProtect and zsh — with pointers to the chapter that goes deeper.
EAppendix E — Sources & further readingWhere the facts in this guide come from and where to check them when they drift — Apple's own documentation and release notes, project changelogs, the community references worth trusting, release calendars for every runtime, and a note on how the guide was researched and how to report an error.