> Source URL: /resources/macos.guide
# macOS Setup Guide

## Before You Start

In this guide you'll be using the **Terminal** -- a built-in app on your Mac that lets you interact with your computer by typing text commands instead of clicking around. Developers use the Terminal to install software, run programs, and manage files. It might feel unfamiliar at first, but you'll only need to copy and paste a few commands and you'll be up and running.

**How to open Terminal:**

1. Press `Cmd+Space` to open Spotlight Search
2. Type **Terminal** and press Enter

A window will appear with a blinking cursor. This is where you'll type (or paste) the commands below.

> **Tip:** To paste a command into Terminal, use `Cmd+V`.

---

## Step 1: Install Homebrew

Homebrew is a tool that lets you install software from the Terminal with simple commands. We'll use it to install everything you need.

Paste this command into Terminal and press **Enter**:

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

A few things will happen:

- It will ask for your **Mac password**. When you type it, nothing will appear on screen -- that's normal. Just type your password and press Enter.
- The installation takes a few minutes. Let it finish completely.

**Important (Apple Silicon Macs):** When the install finishes, Homebrew will print a message that says **"Run these commands in your terminal"** (or similar). Instead of copying those, just paste this single command and press Enter:

```bash
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zshrc && eval "$(/opt/homebrew/bin/brew shellenv)"
```

Then **close Terminal and reopen it** so the change takes effect.

> **What does this do?** It tells your Mac where Homebrew was installed so it can find the `brew` command every time you open Terminal. You only need to do this once.

**Verify Homebrew is installed:**

```bash
brew --version
```

You should see something like `Homebrew 4.x.x`. If you see "command not found," revisit the step above.

---

## Step 2: Install VS Code, Python, and Git

Now use Homebrew to install the three tools you need. Paste these commands into Terminal:

```bash
brew install --cask visual-studio-code
brew install python git
```

This will download and install:

- **Visual Studio Code** -- the code editor we'll use in class
- **Python** -- the programming language
- **Git** -- the tool that lets you work with GitHub repositories

Each install may take a minute or two.

---

## Step 3: Verify Everything Installed

Run each of these commands one at a time:

```bash
code --version
```

```bash
python3 --version
```

```bash
git --version
```

Each one should print a version number (for example, `Python 3.13.1`). If any command says "not found," see the **Troubleshooting** section at the bottom.

> **Note:** On macOS, the Python command is `python3` (not `python`). This is normal.

---

## Step 4: Install the Python Extension in VS Code

VS Code needs one extension to work well with Python.

1. Open **Visual Studio Code** (you can type `code` in Terminal, or find it in your Applications folder)
2. Click the **Extensions** icon in the left sidebar -- it looks like four small squares
3. In the search bar, type **Python**
4. Find the one by **Microsoft** and click **Install**

### Select the Python Interpreter

This tells VS Code which version of Python to use.

1. Press `Cmd+Shift+P` to open the **Command Palette** (a search bar at the top of VS Code)
2. Type **Python: Select Interpreter** and click on it
3. Choose the Python version from the list (it will look something like `Python 3.13.x`)

---

## Step 5: Configure Git

Git needs to know your name and email so it can label your work. Run these two commands in Terminal, replacing the placeholder values with your own information:

```bash
git config --global user.name "Your Name"
```

```bash
git config --global user.email "your-email@example.com"
```

Use the **same email** that is associated with your GitHub account.

---

## Troubleshooting

**"code: command not found"**

1. Open VS Code from your Applications folder
2. Press `Cmd+Shift+P` to open the Command Palette
3. Type **Shell Command: Install 'code' command in PATH** and click on it
4. Close Terminal and reopen it
5. Try `code --version` again

**"brew: command not found"**

Homebrew installed, but Terminal doesn't know where to find it. This is common on newer Macs. Run the single command from the **"Important (Apple Silicon Macs)"** note in Step 1:

```bash
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zshrc && eval "$(/opt/homebrew/bin/brew shellenv)"
```

Then **close Terminal and reopen it**. Try `brew --version` again.

**"python3: command not found"**

Try reinstalling Python through Homebrew:

```bash
brew install python
```

Then close and reopen Terminal and try `python3 --version` again.

**VS Code can't find Python / no interpreter showing up**

1. Make sure you installed the Python extension (Step 4)
2. Press `Cmd+Shift+P`, type **Python: Select Interpreter**, and pick a Python version
3. If no versions appear, try restarting VS Code

---

## When to Ask for Help

You've tried the troubleshooting steps above and something still isn't working? Ask for help! When you do, please include:

- That you're on **macOS**
- Which **step** you're stuck on
- The **exact error message** (a screenshot is even better)


---

## Backlinks

The following sources link to this document:

- [macOS Setup Guide](/resources/resources.index.llm.md)
- [macOS](/resources/local-dev.guide.llm.md)