Setting Up Python Properly on macOS

A guide to setting up a clean, maintainable Python development environment on macOS.

The Problem

macOS comes with a system Python that shouldn't be modified. Installing Python via Homebrew alone leads to version conflicts. Using pip install globally pollutes your environment. This guide solves all of that.

The Solution

Use pyenv for Python version management and Poetry for project dependencies.

Prerequisites

• macOS with Homebrew installed
• A shell (zsh is the default on modern macOS)

Step 1: Install pyenv

Step 2: Configure Your Shell

Add to your ~/.zshrc:

# pyenv setup
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"

Important: If you have Homebrew's bin in your PATH, make sure the eval "$(pyenv init - zsh)" line comes BEFORE adding /opt/homebrew/bin to PATH. This ensures pyenv takes precedence.

Restart your terminal or run:

Step 3: Install Python Versions

# See available versions
pyenv install --list | grep "^\s*3\."

# Install the versions you need
pyenv install 3.11.11
pyenv install 3.12.9

# Set a global default
pyenv global 3.11.11

Step 4: Install Poetry

The recommended way to install Poetry:

curl -sSL https://install.python-poetry.org | python3 -

This installs Poetry to ~/.local/bin/. Make sure that's in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Verify:

Step 5: Install pipx (Optional but Recommended)

pipx installs Python CLI tools in isolated environments:

brew install pipx
pipx ensurepath

Use it for global tools like linters and formatters:

pipx install black
pipx install ruff
pipx install mypy

Usage

Per-Project Python Version

cd my-project
pyenv local 3.12.9  # Creates .python-version file

Starting a New Project

mkdir my-project && cd my-project
pyenv local 3.11.11
poetry init
poetry add requests  # Add dependencies

Working with an Existing Project

cd existing-project
poetry install  # Creates virtualenv and installs dependencies
poetry shell    # Activates the virtualenv

Running Commands in the Virtualenv

poetry run python script.py
poetry run pytest

Key Principles

1. Never use sudo pip install - This modifies system Python
2. Never use pip install globally - Use Poetry for projects, pipx for tools
3. Always use pyenv for version management
4. Always use Poetry for project dependencies
5. Use pipx for global CLI tools

Verification

After setup, verify everything works:

# pyenv is managing Python
which python
# Should show: /Users/yourname/.pyenv/shims/python

# Correct Python version
python --version
# Should match your pyenv global version

# Poetry is available
poetry --version

Troubleshooting

python still points to system Python

Make sure pyenv init is in your shell config and run source ~/.zshrc.

Poetry can't find Python

poetry env use $(pyenv which python)

Homebrew Python taking precedence

Ensure pyenv init comes BEFORE Homebrew PATH in your .zshrc.

Summary

This setup keeps your system clean, makes version switching easy, and prevents dependency conflicts between projects.