Python

Mac Python Setup Guide | Install and Configure Python

Install Python, Xcode, Homebrew, and VS Code on macOS. Complete guide for setting up a professional Python development environment.

By InventiveHQ Team

To set up a professional Python development environment on a Mac, install the Xcode Command Line Tools (for Git and a C compiler), install Homebrew as your package manager, then run brew install python to get a modern Python 3 and pip — never build projects against the system Python. Add VS Code with Microsoft's Python extension as your editor, and create an isolated virtual environment per project with python3 -m venv .venv. The whole setup is five commands and takes about 20 minutes, most of which is Homebrew and the Command Line Tools downloading in the background.

That's the summary an AI Overview will give you. What it can't show you is the order things break in — why installing packages into the system Python quietly corrupts your setup, when Homebrew beats pyenv, and how to prove your environment is wired correctly before you write a line of code. Below is the exact dependency chain as an animated flow, a copy-paste command sequence, a decision table for the choices that actually matter, and a verification checklist that catches the mistakes most tutorials leave you to discover the hard way.

The install order (and why it matters)

Each tool depends on the one before it. Homebrew won't compile without the Command Line Tools; most useful Python packages won't build without a compiler either. Follow the arrows — skipping ahead is where setups go wrong.

macOS Python setup dependency chain Command Line Tools enable Homebrew, which installs Python 3 and VS Code; Python 3 then creates per-project virtual environments. A moving token traces the install order. Command Line Tools Git + C compiler Homebrew package manager Python 3 + pip brew install python VS Code + Python extension Virtual environment python3 -m venv .venv one per project Do not use /usr/bin/python system Python is Apple's, wiped by OS updates

Step 1: Launch Terminal

The Terminal is macOS's command-line interface, similar to Unix/Linux CLI environments since macOS is based on BSD Unix. It's your gateway to installing development tools and managing your Python environment.

How to Access Terminal

  • Press Cmd + Space to open Spotlight search

  • Type "Terminal" and press Enter

  • Or go to Applications → Utilities → Terminal

💡 Pro Tip: Pin Terminal to your Dock for quick access. Right-click the Terminal icon in your Dock and select "Options → Keep in Dock".

Step 2: Install Xcode Command Line Tools

Xcode Command Line Tools provides essential development utilities including Git version control and build tools required by Homebrew. While not strictly required for Python development, these tools are prerequisites for most development workflows.

Open Terminal and run:

xcode-select --install

  • Click "Install" when the dialog appears

  • Accept the license agreement

  • Wait for installation to complete (5-15 minutes)

Alternative: Full Xcode Installation

If you plan to develop iOS apps or need the full Xcode IDE:

  • Open App Store

  • Search for "Xcode"

  • Install Xcode (requires ~15GB disk space)

  • Launch Xcode and install additional components when prompted

Step 3: Install Homebrew Package Manager

Homebrew is the essential package manager for macOS, similar to apt-get for Ubuntu or yum for Red Hat Linux. It simplifies installing and managing development tools, applications, and libraries from the command line.

Installation Command

In your Terminal, run the official Homebrew installation script:

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

  • Enter your password when prompted

  • Press Enter to continue installation

  • Follow any additional setup instructions displayed

Understanding Homebrew Package Types

Homebrew offers two package types:

  • Formulas (brew): Command-line tools and libraries

  • Casks (brew –cask): GUI applications

Advertisement

Example Usage

# Install a GUI application
brew install --cask firefox

# Install a command-line tool
brew install git

Test your Homebrew installation by running one of the above commands. Search for packages at formulae.brew.sh.

Step 4: Install Visual Studio Code

Visual Studio Code is the world's most popular code editor, offering excellent Python support with IntelliSense, debugging, Git integration, and extensive extension marketplace. Built on Electron, it runs consistently across all platforms.

brew install --cask visual-studio-code

Alternative: Direct Download

You can also download VS Code directly from code.visualstudio.com/download and install manually.

💡 Essential Extensions: After installing VS Code, add the Python extension by Microsoft for the best Python development experience with syntax highlighting, IntelliSense, and debugging support.

Step 5: Install Python 3

Older Macs shipped Python 2.7, but Apple removed it in macOS 12.3 (Monterey, March 2022) — Python 2 reached end-of-life on January 1, 2020. On current macOS, /usr/bin/python3 is only a stub that triggers the Command Line Tools installer; it is not a Python you should build projects against. Install your own Python 3 with Homebrew so upgrades and packages stay under your control, not Apple's.

Homebrew vs. pyenv: which Python manager should you use?

Both get you a real Python 3. Pick based on how many versions you need to juggle.

ApproachBest forOne Python or many?Upgrade pathVerdict
Homebrew (brew install python)Most developers, one current project stackOne (the latest)brew upgrade pythonStart here — simplest, fewest moving parts
pyenv (brew install pyenv)Testing across 3.11 / 3.12 / 3.13, per-project pinningMany, switchablepyenv install 3.x.yUse when you truly need multiple versions
System /usr/bin/python3Apple's own scripts onlyFixed by macOSDon't — it's wiped by OS updatesNever for project work
python.org installerGUI-only users who avoid the terminalOne per downloadManual re-downloadFine, but Homebrew is easier to maintain

If you're unsure, use Homebrew. You can add pyenv later — many developers install pyenv through Homebrew when a project finally needs a second Python version.

Install Python 3 via Homebrew

brew install python

This installs the latest Python 3 version along with pip3 (Python's package installer).

Verify Installation

# Check Python version
python3 --version

# Check pip version
pip3 --version

⚠️ Important: Always use python3 and pip3 commands on macOS to ensure you're using Python 3, not the system's Python 2.7.

Step 6: Install Virtual Environments

Virtual environments create isolated Python environments for each project, preventing package conflicts and ensuring reproducible setups. This is essential for professional Python development, allowing different projects to use different package versions without interference.

Python 3 ships with the venv module, so you no longer need to install virtualenv for typical work. Create and activate an environment inside your project folder:

# Create a virtual environment named .venv in the current project
python3 -m venv .venv

# Activate it (macOS/Linux)
source .venv/bin/activate

# Your prompt now shows (.venv); pip installs land only here
pip install requests flask

# Freeze exact versions for reproducibility
pip freeze > requirements.txt

# Deactivate when done
deactivate

Naming the folder .venv is a common convention that VS Code auto-detects. Add .venv/ to your .gitignore — you commit requirements.txt, not the environment itself.

When to reach for standalone virtualenv

The separate virtualenv package is faster than venv and supports older Python versions. Install it only if you specifically need those features:

pip3 install --user virtualenv

💡 Pro Tip: Create a dedicated folder for your Python projects and always activate the appropriate virtual environment before working on a project.

Step 7: Test Your Development Environment

Let's verify everything is working correctly by creating and running a simple Python program in VS Code.

Create Your First Python Program

  • Launch Visual Studio Code

  • Create a new file: File → New File

  • Type the following code:

print('Hello World!')
print('Python development environment is ready!')

  • Save the file as hello.py

  • Open Terminal in VS Code: Terminal → New Terminal

  • Run your program:

python3 hello.py

You should see both messages printed in the terminal. Congratulations! Your Mac Python development environment is now fully configured and ready for professional development.

Verification checklist: prove it's wired correctly

Before you trust the setup, run these three checks. Each one catches a classic mistake that silently sends packages to the wrong place.

CheckCommandWhat a correct result looks like
Python is yours, not Apple'swhich python3A Homebrew path like /opt/homebrew/bin/python3 (Apple Silicon) or /usr/local/bin/python3 (Intel) — not /usr/bin/python3
Version matches what you installedpython3 --versionThe 3.x version Homebrew installed (e.g. Python 3.13.x)
pip installs into Homebrew Pythonpip3 --versionEnds with the same Homebrew path shown above
venv isolation worksActivate a venv, then which pythonA path inside your project's .venv/bin/ folder

If which python3 returns /usr/bin/python3, your PATH still favors the system stub — reopen Terminal (or run the Homebrew eval "$(...)" line the installer printed) so the Homebrew bin directory comes first. Getting these four checks right is the difference between packages landing where you expect and hours lost to "it works in one terminal but not the other."

Quick Reference: All Commands

For easy reference, here are all the installation commands in sequence. Copy and paste these into Terminal one at a time:

# Install Xcode Command Line Tools
xcode-select --install

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

# Install VS Code
brew install --cask visual-studio-code

# Install Python 3
brew install python

# Create an isolated environment per project (built into Python 3)
python3 -m venv .venv
source .venv/bin/activate

Next Steps for Python Development

  • Install the Python extension in VS Code

  • Learn Git version control basics

  • Explore Python frameworks like Django or Flask

  • Set up project-specific virtual environments

  • Configure VS Code for Python debugging

Frequently Asked Questions

Does macOS come with Python already installed?

Modern macOS (Monterey 12.3 and later) no longer bundles Python 2.7, and it never shipped a general-purpose Python 3 you should build projects against. There is a stub at /usr/bin/python3 that only exists to prompt you to install the Xcode Command Line Tools. For real development, install your own Python 3 with Homebrew (brew install python) or a version manager like pyenv so upgrades and packages stay under your control, not Apple's.

Should I use the system Python on my Mac?

No. Any Python that ships with macOS or the Command Line Tools is there for Apple's own scripts. Installing packages into it with sudo pip can break system tooling and gets wiped by OS updates. Always install a separate Homebrew or pyenv Python and do project work inside virtual environments.

What is the difference between python and python3 on macOS?

On a clean Mac, "python" often does not exist at all (the Python 2 alias was removed), while "python3" points at whatever Python 3 is first on your PATH. After installing Homebrew Python, python3 resolves to the Homebrew build. Inside an activated virtual environment, plain "python" and "pip" become safe because they point at that environment's interpreter.

Do I need Xcode Command Line Tools just to run Python?

Not to run pure-Python scripts, but you need them in practice. Homebrew requires the Command Line Tools to compile formulas, and many popular packages (numpy, pandas, cryptography, lxml) need a C compiler to build wheels from source. Running xcode-select --install once gets you Git and the compiler toolchain without the full 15 GB Xcode app.

Homebrew or pyenv for managing Python on a Mac?

Use Homebrew if you want one current Python and simple upgrades — it is the fastest path for most people. Use pyenv when you need several Python versions side by side (for example testing against 3.11, 3.12, and 3.13) or want to pin an exact version per project. The two coexist fine; many developers install pyenv itself via Homebrew.

Why do I need a virtual environment for every project?

A virtual environment gives each project its own isolated set of installed packages, so Project A can use Flask 2 while Project B uses Flask 3 without conflict. It also keeps your base Python clean and makes setups reproducible via a requirements.txt file. Python 3 ships venv built in — python3 -m venv .venv — so you no longer need to install virtualenv separately.

Is virtualenv still needed, or should I use venv?

For most work, use the built-in venv module (python3 -m venv .venv); it covers what the vast majority of projects need and requires no extra install. The standalone virtualenv package is faster and supports older Python versions, so reach for it only if you specifically need those features. This guide's virtualenv step is optional once you are on Python 3.

How do I verify my Mac Python environment is set up correctly?

Run three checks — which python3 should point at a Homebrew or pyenv path (not /usr/bin), python3 --version should report the version you installed, and after creating and activating a venv, "which python" should point inside your project's .venv folder. If all three match your expectations, packages you install will land in the right place.

Related articles

From the Inventive HQ family
OmniCanvas Notes
Visual thinking on an infinite canvas.

Notes, sketches and ideas laid out spatially instead of in a list. For people who think in diagrams and keep outgrowing linear note apps.

Take a look