> ## Documentation Index
> Fetch the complete documentation index at: https://fastapi2day.codewithsiva.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing Python on macOS: Official Installer and Homebrew

> Step-by-step guide to installing Python on a Mac using the official installer or Homebrew, with shell configuration tips and troubleshooting advice.

macOS ships with a system Python that Apple uses for internal purposes. You should leave that version untouched and install your own Python 3 alongside it. There are two popular approaches: downloading the official installer from python.org (the simplest path) or using the Homebrew package manager (preferred if you already use Homebrew for other tools). Both options are covered below — choose the one that suits you.

## Check what you already have

Before installing, it is worth checking whether a suitable Python 3 is already present on your machine. Open a Terminal window (`Cmd + Space`, type "Terminal", press Enter) and run:

```bash theme={null}
python3 --version
```

If you see a recent Python 3 version (3.10 or later is fine for this course), you may already be set. If the command is not found, or the version is older than you'd like, continue with the installation steps below.

<Note>
  Never rely on the `python` command on macOS without checking what it points to — on some systems it invokes Python 2, which is end-of-life. Always use `python3` unless you have explicitly configured an alias.
</Note>

## Option A: Official installer from python.org

This is the recommended approach for most learners.

<Steps>
  <Step title="Download the installer">
    Go to [python.org/downloads](https://www.python.org/downloads/). The site detects macOS and shows the latest stable release. Click the download button to get the `.pkg` file.

    <Tip>
      Always download from the official python.org website to ensure you receive the signed, verified release.
    </Tip>
  </Step>

  <Step title="Run the package installer">
    Open the downloaded `.pkg` file. The Python installer will launch. Click through the following screens:

    1. **Introduction** — click **Continue**.
    2. **License** — click **Continue**, then **Agree**.
    3. **Installation Type** — click **Install**.
    4. Enter your Mac password when prompted.
    5. Wait for the progress bar to finish.
    6. Click **Close** when you see **"The installation was successful"**.
  </Step>

  <Step title="Install SSL certificates">
    After the installer closes, look in your Applications folder for a folder named **Python 3.x**. Inside it, double-click **Install Certificates.command** to run it. This is necessary for making HTTPS requests from Python — which you will do when calling AI APIs.

    <Warning>
      Skipping the certificate install causes `ssl.SSLCertVerificationError` errors when your code tries to reach any HTTPS endpoint. Run the command now to avoid this later.
    </Warning>
  </Step>

  <Step title="Open a new Terminal window">
    Close your current Terminal window and open a fresh one. This ensures the shell picks up the updated PATH that the installer wrote to your profile.
  </Step>

  <Step title="Verify the installation">
    ```bash theme={null}
    python3 --version
    ```

    You should see the version you just installed. Also confirm `pip3` is available:

    ```bash theme={null}
    pip3 --version
    ```
  </Step>

  <Step title="Test the interpreter">
    Launch the Python REPL:

    ```bash theme={null}
    python3
    ```

    You will see the `>>>` prompt:

    ```text theme={null}
    Python 3.13.5 (v3.13.5:0fa1754080, Jul 29 2025, 09:45:56) [Clang 15.0.0] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>>
    ```

    Try a command:

    ```python theme={null}
    print("Hello from Python on macOS!")
    ```

    Exit with `exit()` or **Ctrl + D**.
  </Step>
</Steps>

## Option B: Homebrew installation

If you use [Homebrew](https://brew.sh) to manage tools on your Mac, installing Python through it keeps everything managed in one place.

<Steps>
  <Step title="Install Homebrew (if not already installed)">
    Open Terminal and run:

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

    Follow the on-screen prompts. On Apple Silicon Macs (M1/M2/M3), Homebrew installs to `/opt/homebrew/` — the installer will tell you to add it to your PATH and show you the exact command to run.
  </Step>

  <Step title="Install Python">
    ```bash theme={null}
    brew install python@3
    ```

    Homebrew will install Python 3 and create symlinks in `/opt/homebrew/bin/` (Apple Silicon) or `/usr/local/bin/` (Intel).
  </Step>

  <Step title="Verify the installation">
    Open a new Terminal window, then:

    ```bash theme={null}
    python3 --version
    pip3 --version
    ```
  </Step>
</Steps>

<Note>
  Homebrew Python lives in a different directory than the python.org installer. Both work correctly for this course. If you later see tools pointing to the wrong Python, `which python3` will show you exactly which binary is being used.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'python3' command not found after installation" icon="circle-exclamation">
    The most common cause is that your shell's PATH was not updated yet.

    **Step 1**: Close Terminal completely (Cmd + Q) and open a new window, then try again.

    **Step 2**: If still not found, check that Python is installed:

    ```bash theme={null}
    ls /Library/Frameworks/Python.framework/Versions/
    ```

    **Step 3**: Add Python to your PATH manually. For Zsh (the default macOS shell since Catalina):

    ```bash theme={null}
    echo 'export PATH="/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    ```

    For Bash (older macOS or custom setup):

    ```bash theme={null}
    echo 'export PATH="/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH"' >> ~/.bash_profile
    source ~/.bash_profile
    ```
  </Accordion>

  <Accordion title="'python' command not found (only 'python3' works)" icon="code">
    This is expected behaviour on macOS — the `python` command is not created automatically to avoid conflicts with the system Python. You have two options:

    **Option 1** (recommended): Always type `python3`. It's a small habit change and keeps things unambiguous.

    **Option 2**: Create a shell alias so `python` maps to `python3`:

    ```bash theme={null}
    echo 'alias python=python3' >> ~/.zshrc
    echo 'alias pip=pip3' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Accordion>

  <Accordion title="SSL / certificate verification errors" icon="lock">
    If you see errors like `ssl.SSLCertVerificationError` when running Python code that makes HTTPS requests:

    **Fix 1**: Run the certificate installer that comes with Python:

    ```bash theme={null}
    /Applications/Python\ 3.*/Install\ Certificates.command
    ```

    **Fix 2**: Install or upgrade the `certifi` package:

    ```bash theme={null}
    pip3 install --upgrade certifi
    ```
  </Accordion>

  <Accordion title="Managing multiple Python versions" icon="code-branch">
    If you have more than one Python version installed, you can call a specific one by including the version number:

    ```bash theme={null}
    python3.13 --version
    python3.12 --version
    ```

    To see all installed versions:

    ```bash theme={null}
    ls -la /usr/local/bin/python*
    # or on Apple Silicon:
    ls -la /opt/homebrew/bin/python*
    ```

    For advanced version management across projects, consider [pyenv](https://github.com/pyenv/pyenv), which is installable via Homebrew:

    ```bash theme={null}
    brew install pyenv
    ```
  </Accordion>
</AccordionGroup>

## Next steps

<Card title="Continue to VS Code Introduction" icon="arrow-right" href="/getting-started/vscode-introduction">
  Install and configure Visual Studio Code as your Python editor.
</Card>