macOS Installation Guide

Before you can work through Module 0.4 (VS Code) and onward, your MacBook needs the program’s toolchain installed. This guide (about 60–90 minutes, mostly waiting for downloads) walks you through every install, with a verification step for each so you’ll know it worked before you move on.

You only do this once. After this, your machine is ready for the entire 8-week program.

If a step fails, don’t panic — read the error message, check §13 (Troubleshooting), and ask in #help on Discord. Most failures here are network hiccups or a missing prerequisite that the next section covers.

1. What you’re about to install

Eleven things, in order:

Total disk space: ~10 GB. Total install time: 60–90 minutes (most of it is downloads running in the background while you read the next step).

2. Xcode Command Line Tools

Open Terminal (Cmd + Space → type Terminal → Enter). Run:

$ xcode-select --install

A system dialog will pop up offering to install the Command Line Tools. Click Install, agree to the license, and wait — this download is ~1 GB and can take 5–15 minutes.

When it finishes, verify:

$ git --version
git version 2.x.x

If git reports a version, you’re done with this step. If you instead see “command not found,” the install didn’t finish — re-run xcode-select --install and try again.

3. Homebrew

Homebrew is the package manager we’ll use for nearly every later step.

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

When the installer finishes, it prints two echo commands to add brew to your shell’s PATH. Copy and run those exact two commands — they look like this on Apple Silicon Macs:

$ echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
$ eval "$(/opt/homebrew/bin/brew shellenv)"

Verify:

$ brew --version
Homebrew 4.x.x

If brew reports a version, you’re set.

4. Node 22 and pnpm

$ brew install node@22
$ brew link --overwrite node@22

The --overwrite flag tells Homebrew this is the Node we want on PATH if another version was somehow already there.

Then enable pnpm via Corepack (Corepack ships inside Node, so no separate install):

$ corepack enable pnpm

Verify:

$ node --version
v22.x.x
$ pnpm --version
10.x.x

5. uv and Python 3.13

uv is the modern Python toolchain — it installs Python versions, manages virtual environments, and resolves dependencies, all in one tool.

$ brew install uv
$ uv python install 3.13

The second command downloads and installs Python 3.13 to a managed location (no fighting with system Python).

Verify:

$ uv --version
uv 0.x.x
$ uv python list --only-installed
cpython-3.13.x-macos-...   (installed)

You’ll meet uv again in Module 0.8 (Python orientation) — that’s where you’ll learn to use it. For now you just need it on PATH.

6. Docker Desktop

$ brew install --cask docker

The --cask flag tells Homebrew this is a graphical application, not a CLI.

After install: open Docker Desktop from Spotlight (Cmd + Space → “Docker”). Accept the license, sign in or skip the sign-in (optional), and let the engine start. The Docker whale icon in your menu bar should stop animating after ~30 seconds — that means the daemon is running.

Verify:

$ docker --version
Docker version 27.x.x, ...
$ docker run hello-world
Hello from Docker!
...

The second command pulls a tiny test image and runs it. If you see “Hello from Docker!” you’re set.

7. Ollama

$ brew install ollama
$ brew services start ollama

brew services start ollama runs Ollama in the background — it’ll auto-start on every login from now on.

Verify:

$ ollama --version
ollama version is 0.x.x
$ ollama list
NAME      ID    SIZE    MODIFIED
(empty — that's fine)

We’ll pull actual models (Gemma 4 E4B or Qwen 3.5 9B) in Week 2 when you first need them — no need to download multi-gigabyte model weights today.

8. GitHub CLI

$ brew install gh
$ gh auth login

gh auth login walks you through authenticating with your GitHub account. Choose:

• GitHub.com (not Enterprise)
• HTTPS for protocol
• Yes authenticate Git
• Login with a web browser (easiest)

A code appears in your terminal. Open the URL it gives you, paste the code, approve the access — and you’re authenticated.

Verify:

$ gh auth status
✓ Logged in to github.com account <your-username>

9. Azure CLI and Bicep

$ brew install azure-cli
$ az bicep install

The first installs the Azure CLI (az); the second installs the Bicep templating engine as a CLI subcommand. We’ll use both in Week 1 to deploy your first Socratic Angle skeleton.

Verify:

$ az --version
azure-cli   2.x.x
$ az bicep version
Bicep CLI version 0.x.x

You don’t need to az login today — we’ll provision your Azure subscription in class on Day 1.

10. Visual Studio Code

$ brew install --cask visual-studio-code

When this finishes, run VS Code once from Spotlight (Cmd + Space → “Visual Studio Code”) so macOS registers it as a trusted app. Then close it.

Now enable the code command-line launcher: open VS Code, press Cmd + Shift + P to open the Command Palette, type Shell Command: Install 'code' command in PATH, and hit Enter. Close the terminal and reopen it for the change to take effect.

Verify:

$ code --version
1.9x.x

11. VS Code extensions

The cohort’s standard extension set, installed in one command:

$ code --install-extension anthropic.claude-code \
       --install-extension eamodio.gitlens \
       --install-extension Prisma.prisma \
       --install-extension dbaeumer.vscode-eslint \
       --install-extension esbenp.prettier-vscode \
       --install-extension bradlc.vscode-tailwindcss \
       --install-extension usernamehw.errorlens \
       --install-extension rangav.vscode-thunder-client \
       --install-extension ms-azuretools.vscode-docker \
       --install-extension ms-azuretools.vscode-azurecontainerapps \
       --install-extension humao.rest-client

Each extension is small (~1–10 MB), so the whole batch installs in under a minute.

Verify by opening VS Code, clicking the Extensions icon in the Activity Bar (left sidebar), and checking that all eleven appear under “Installed.”

You’ll learn what each one does in Module 0.4 (VS Code Essentials).

12. Claude Code

$ npm install -g @anthropic-ai/claude-code
$ claude --version

npm came in with Node 22 (§4), so this works as long as that step succeeded.

Now log in:

$ claude login

This opens a browser window — sign in with the Anthropic account from your account-setup module (Module 0.2). When the browser redirects to a “you can close this window” page, you’re authenticated.

Verify:

$ claude --version
0.x.x (Claude Code)

You can also launch Claude Code inside VS Code: open the editor, click the Claude icon in the Activity Bar, and you should see your conversation panel.

13. Troubleshooting

brew install says “command not found: brew” — Homebrew installed but isn’t on PATH. Run the two echo + eval lines from §3 again, then open a new terminal window.

brew install fails with “permission denied” — your shell isn’t pointed at the right brew directory. Confirm you’re on Apple Silicon: uname -m should print arm64. If it does, brew should be at /opt/homebrew/bin/brew. If uname -m prints x86_64, you’re on an Intel Mac and the brew prefix is /usr/local/bin/brew — use that path in the shellenv command.

Docker Desktop won’t start — open Docker Desktop manually from Applications once after install. macOS will prompt to allow it; click Allow. Then try docker run hello-world again.

gh auth login opens the wrong browser / hangs — close it, copy the URL from the terminal manually, paste into Chrome, paste the code, approve. The auth completes in the terminal once you finish in the browser.

code command not found — re-run the “Install ‘code’ command in PATH” step from §10. Some shells (zsh with custom configs) require a new terminal window to pick it up.

npm install -g says “permission denied” — Homebrew’s Node should install to a user-writable location, so this shouldn’t happen. If it does, don’t sudo it — instead, check that your Node came from Homebrew: which node should return /opt/homebrew/bin/node. If it returns /usr/local/bin/node or /usr/bin/node, you have a non-Homebrew Node interfering. Run brew link --overwrite node@22 again.

14. The verification checklist

Run all of these. Every line should print a version number — no errors, no “command not found.”

$ git --version
$ brew --version
$ node --version
$ pnpm --version
$ uv --version
$ docker --version
$ ollama --version
$ gh auth status
$ az --version
$ az bicep version
$ code --version
$ claude --version

If every line printed cleanly, screenshot the terminal output and post it in #wins on Discord with the message “Setup complete — toolchain installed.” You’re ready for Module 0.4 (VS Code Essentials) and the rest of Get Started.

15. The cheat sheet

What’s next

With your toolchain installed, you can take on the rest of Get Started. The next module to complete is 0.4 — VS Code Essentials, which assumes you have VS Code and the cohort extensions installed (you just did that in §10 and §11). After that, the remaining modules build on this foundation — HTML/CSS, JavaScript, TypeScript, Python, DevTools, the Day-1 readiness check, and the Process & Methodology reading.

See you in #wins after the verification screenshot.