Skip to content

PYTHON_MAC.md

Latest commit

 

History

History
551 lines (397 loc) · 17.1 KB

PYTHON_MAC.md

File metadata and controls

551 lines (397 loc) · 17.1 KB

Python Setup Guide for Beginners 🐍

What is Python and Why Multiple Versions?

Python is a programming language, and like any software, it gets updated with new features, bug fixes, and security improvements. Different projects might need different Python versions, so we often have multiple versions installed.

Think of it like having different versions of an app on your phone - sometimes you need the latest features, sometimes you need stability.

Our Current Python Setup

After our cleanup, here's what we have:

🎯 Recommended Setup (What You Should Use)

# Your project's virtual environment (BEST CHOICE)
Python 3.12.11 ('.venv': Poetry) - Use this for agent-catalog project

🛠️ Available Python Versions

Version Location Purpose When to Use
Python 3.12.11 /opt/homebrew/bin/python3.12 Main development New projects, daily coding
Python 3.13.5 /opt/homebrew/bin/python3.13 Latest features Testing newest Python features
Python 3.9.6 /usr/bin/python3 System Python Leave alone (macOS needs this)

Understanding the System Python (3.9.6)

🤔 Why Keep Python 3.9.6?

Short Answer: macOS (your operating system) uses it internally.

Longer Explanation:

  • Apple includes Python 3.9.6 as part of macOS
  • Some macOS tools and scripts expect to find Python at /usr/bin/python3
  • If we remove or change it, we might break macOS functionality
  • It's like the "factory installed" software - safer to leave it alone

💡 Should We Make Python 3.13 the Default?

Yes, we can and should! Here's how:

Current Situation:

python3 --version  # Shows Python 3.9.6 (old!)

After Optimization:

python3 --version  # Would show Python 3.13.5 (modern!)

How It Works:

  • System Python stays safe at /usr/bin/python3 (macOS happy)
  • Your terminal uses modern Python when you type python3 (You happy)
  • Best of both worlds!

Virtual Environments Explained 🏠

What is a Virtual Environment?

Think of virtual environments like separate apartments:

  • Each project gets its own "apartment" (environment)
  • Each apartment has its own Python version and packages
  • Changes in one apartment don't affect others
  • No conflicts between different projects

Our Project's Virtual Environment

# Location: /Users/kaustavghosh/Desktop/agent-catalog-quickstart/.venv
# Python Version: 3.12.11
# Managed by: Poetry
# Status: ✅ Ready to use

How to Use Each Python Version

🎯 For Your Agent Catalog Project (Recommended)

# Activate the project environment
poetry shell

# Or run commands directly
poetry run python your_script.py

🔧 For New Projects

# Create a new project with specific Python version
/opt/homebrew/bin/python3.12 -m venv my_new_project
cd my_new_project
source bin/activate

🧪 For Testing Latest Features

# Use Python 3.13
/opt/homebrew/bin/python3.13 -m venv test_env
cd test_env
source bin/activate

Common Commands

📋 Checking Python Versions

# Check what 'python3' points to
python3 --version

# Check specific versions
/opt/homebrew/bin/python3.12 --version
/opt/homebrew/bin/python3.13 --version
/usr/bin/python3 --version

# See all Python installations
ls -la /opt/homebrew/bin/python*

🔍 Working with Virtual Environments

# Check current project's environment
poetry env info

# Activate project environment
poetry shell

# Install packages in project
poetry add package_name

# Run scripts in project environment
poetry run python script.py

What We Cleaned Up (And Why)

❌ Removed (Problematic/Outdated)

What Why Removed
Python 3.11.x Outdated, not needed for current project
Python 3.12.8 Older patch version (3.12.11 is newer)
Broken symlinks Pointing to deleted Python installations
Old .python-version Referencing removed Python version

✅ Kept (Useful/Essential)

What Why Kept
Python 3.9.6 (system) Required by macOS
Python 3.12.11 Project requirement, stable
Python 3.13.5 Latest features, future-proofing
Poetry virtual env Project dependencies

The Complete Cleanup Process 🧹

Here's the detailed step-by-step process we used to clean up your Python installation. Don't run these commands again - this is just for educational purposes!

🔍 Step 1: Investigation Phase

First, we examined what Python versions were installed:

# Check Homebrew Python installations
brew list | grep python
# Result: python@3.12, python@3.13 (good to keep)

# Check pyenv-managed versions
pyenv versions
# Result: Found Python 3.12.8 (older patch version)

# Check system Python locations
ls -la /usr/local/bin/python* /opt/homebrew/bin/python* /usr/bin/python*
# Result: Found old symlinks and framework installations

🗑️ Step 2: Remove Outdated pyenv Version

# Remove the older Python 3.12.8 from pyenv
pyenv uninstall -f 3.12.8
# ✅ Result: Removed older patch version

# Reset pyenv to use system Python
pyenv global system
# ✅ Result: No longer forcing old Python version

Why this step?

  • Python 3.12.8 was an older patch version
  • Python 3.12.11 (Homebrew) is newer and better maintained
  • Prevents version conflicts

🔗 Step 3: Clean Up Broken Symlinks

# Remove old Python 3.11 symlinks in /usr/local/bin
sudo rm -f /usr/local/bin/python /usr/local/bin/python3
# ✅ Result: Removed broken links pointing to deleted Python 3.11

Why this step?

  • These symlinks pointed to Python 3.11 framework we were going to remove
  • Broken symlinks cause confusion and errors
  • Better to have no link than a broken link

🗂️ Step 4: Remove Python Framework Installation

# Remove the entire Python 3.11 framework
sudo rm -rf /Library/Frameworks/Python.framework/Versions/3.11
# ✅ Result: Freed up disk space, removed outdated Python

Why this step?

  • Python 3.11 was outdated (your project needs 3.12+)
  • Framework installations can conflict with Homebrew versions
  • This was taking up unnecessary disk space

📄 Step 5: Clean Up Configuration Files

# Remove .python-version file pointing to deleted version
rm .python-version
# ✅ Result: Removed reference to deleted Python 3.12.8

Why this step?

  • The file was telling pyenv to use Python 3.12.8 (which we removed)
  • This was causing "version not installed" errors
  • Better to use default system behavior

🧽 Step 6: General Cleanup

# Clean up Homebrew caches and orphaned files
brew cleanup
# ✅ Result: Freed up additional disk space

Why this step?

  • Removes cached files from deleted installations
  • Frees up disk space
  • Keeps Homebrew installation clean

🔧 Step 7: Reinstall Poetry

# Install Poetry using the clean Python 3.12 installation
curl -sSL https://install.python-poetry.org | /opt/homebrew/bin/python3.12 -
# ✅ Result: Poetry installed and working with correct Python version

Why this step?

  • Poetry wasn't found in PATH after cleanup
  • Installing with Python 3.12 ensures compatibility
  • Poetry is essential for this project's dependency management

🎯 Step 8: Make Python 3.13 the Default

# Add Homebrew Python to PATH priority
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
# ✅ Result: Homebrew bin directory added to front of PATH

# Apply the changes
source ~/.zshrc
# ✅ Result: Modern Python now default while system stays safe

Why this step?

  • Makes Python 3.13.5 your daily default instead of 3.9.6
  • Keeps system Python completely safe and untouched
  • Provides modern Python features for development
  • Still allows specific version access when needed

✅ Step 9: Final Verification

# Verify the complete setup
python3 --version                   # ✅ Python 3.13.5 (new default!)
which python3                       # ✅ /opt/homebrew/bin/python3
/usr/bin/python3 --version         # ✅ Python 3.9.6 (system safe)
poetry --version                    # ✅ Poetry (version 2.1.3)
poetry run python --version        # ✅ Python 3.12.11 (project env)
poetry env info                     # ✅ Project env using Python 3.12.11

📊 Before vs After Comparison

Before Cleanup:

❌ Python 3.9.6 (system) - outdated default
❌ Python 3.11.x (framework) - outdated, conflicting
❌ Python 3.12.8 (pyenv) - old patch version
❌ Python 3.12.11 (homebrew) - good but not prioritized
❌ Python 3.13.5 (homebrew) - good but unused
❌ Broken symlinks and configs
❌ Poetry not working

After Cleanup & Optimization:

✅ Python 3.13.5 (homebrew) - NEW DEFAULT for daily use
✅ Python 3.12.11 (homebrew) - project standard
✅ Python 3.9.6 (system) - safe, untouched (macOS protected)
✅ Clean configurations
✅ Working Poetry installation
✅ Proper virtual environment
✅ Modern Python as default while keeping system safe

🎯 Key Principles Used

  1. Safety First: Never touched system Python (/usr/bin/python3)
  2. Keep Modern Versions: Preserved Python 3.12+ installations
  3. Remove Conflicts: Eliminated competing installations
  4. Clean Configs: Removed stale configuration files
  5. Verify Everything: Tested each component after cleanup

🚫 What We Deliberately DIDN'T Remove

  • System Python 3.9.6: macOS needs this
  • Homebrew Python 3.12: Required for project
  • Homebrew Python 3.13: Latest stable version
  • Project .venv folder: Contains all project dependencies

💡 Lessons for Future Cleanups

  1. Always investigate first - understand what you have before removing
  2. Start with least risky changes - remove pyenv versions before system files
  3. Keep backups - especially of working virtual environments
  4. Verify at each step - make sure each removal doesn't break anything
  5. Document everything - know what you removed and why

This cleanup process transformed a messy Python installation into a clean, professional development environment! 🚀

✅ Python 3.13 is Now Your Default!

We've successfully implemented Python 3.13 as your default Python while keeping the system safe!

🎯 Current Status (IMPLEMENTED):

# Your new default (modern Python)
python3 --version          # ✅ Python 3.13.5
which python3              # ✅ /opt/homebrew/bin/python3

# System Python (safe & untouched)
/usr/bin/python3 --version # ✅ Python 3.9.6 (macOS protected)

# Project environment (perfect)
poetry run python --version # ✅ Python 3.12.11 (in virtual env)

🔧 How We Did It:

We added Homebrew's bin directory to the front of your PATH in ~/.zshrc:

# This line was added to ~/.zshrc
export PATH="/opt/homebrew/bin:$PATH"

🛡️ Safety Guaranteed:

  • ✅ System Python untouched - macOS functionality preserved
  • ✅ Modern Python as default - better development experience
  • ✅ Project environment intact - agent-catalog works perfectly
  • ✅ Reversible change - can be undone if needed

🎯 What This Means for You:

When You Type You Get Purpose
python3 Python 3.13.5 Daily development work
python3.12 Python 3.12.11 Specific version if needed
/usr/bin/python3 Python 3.9.6 System Python (unchanged)
poetry run python Python 3.12.11 Your project's requirements

Best Practices 📝

✅ Do This:

  • Always use virtual environments for projects
  • Use Poetry for this agent-catalog project
  • Keep system Python untouched
  • Specify Python version when creating new projects
  • Update packages regularly in virtual environments

❌ Don't Do This:

  • Don't modify /usr/bin/python3 (system Python)
  • Don't install packages globally with pip
  • Don't delete system Python
  • Don't mix packages between different projects

Troubleshooting 🔧

Common Issues:

  1. "Command not found: poetry"

    # Poetry is in ~/.local/bin, add to PATH:
export PATH="$HOME/.local/bin:$PATH"

  2. "Wrong Python version in project"

    poetry env use /opt/homebrew/bin/python3.12

  3. "Package conflicts"

    # Use virtual environments!
poetry shell  # for this project

Final Verification & Status 🎯

✅ Your Current Python Setup (PERFECT!):

# Test your setup right now:
python3 --version                # Should show: Python 3.13.5
which python3                    # Should show: /opt/homebrew/bin/python3
/usr/bin/python3 --version       # Should show: Python 3.9.6 (system safe)
poetry run python --version     # Should show: Python 3.12.11 (project)

🏆 Achievement Unlocked:

✅ What You Have 📝 Description
Modern Default Python 3.13.5 when you type python3
Project Environment Python 3.12.11 in your agent-catalog virtual env
System Safety Python 3.9.6 preserved for macOS
Clean Setup No conflicting installations
Professional Tools Poetry working perfectly
Best Practices Virtual environments for isolation

Summary 🎯

You now have the IDEAL Python development setup:

  • ✅ Modern Python 3.13.5 as your daily default
  • ✅ Project-specific Python 3.12.11 for agent-catalog
  • ✅ System Python 3.9.6 safely preserved for macOS
  • ✅ Clean virtual environment with all dependencies
  • ✅ Poetry for professional dependency management
  • ✅ Zero conflicts between different Python versions

🚀 Ready for Development:

  • Daily coding: Just type python3 (gets 3.13.5)
  • Agent-catalog project: Use poetry shell or poetry run
  • New projects: Create with /opt/homebrew/bin/python3.12 -m venv
  • System tools: macOS continues working normally

Your setup now follows industry best practices and gives you the best development experience possible! 🎉

Cross-Platform Development 🌍

🐧 Working with Linux Systems:

If you also work on Linux systems, be aware of platform differences:

Linux-Specific Issues:

  • EXTERNALLY-MANAGED error: Ubuntu/Debian systems block pip by default
  • Solution documented: See PYTHON_LINUX.md for the complete fix
  • Different approach needed: Linux requires removing restriction file

macOS vs Linux Python Management:

Aspect macOS (This Guide) Linux (Ubuntu/Debian)
System Python /usr/bin/python3 (3.9.6) /usr/bin/python3 (varies)
Package Manager Homebrew + pip work together apt conflicts with pip
Default pip Works normally Blocked by EXTERNALLY-MANAGED
Best Practice Use Homebrew versions Remove restriction file
Virtual Environments Optional, Poetry recommended Optional after fix

Cross-Platform Project Setup:

# Works on both macOS and Linux (after our fixes)
pip install package-name        # Standard approach
poetry install                  # For this agent-catalog project
python3 -m venv env            # Virtual env if needed

🔄 Switching Between Systems:

Your agent-catalog project works identically on both platforms:

# Same commands work everywhere
poetry shell
poetry run python script.py
poetry add new-package

📋 Cross-Platform Checklist:

  • ✅ macOS: Modern Python as default (this guide)
  • ✅ Linux: EXTERNALLY-MANAGED restriction removed (see PYTHON_LINUX.md)
  • ✅ Both: Poetry working for agent-catalog project
  • ✅ Both: Standard pip workflow restored
  • ✅ Both: Professional development environment

Platform-Specific Quick References

🍎 macOS Quick Commands:

python3 --version              # Python 3.13.5 (Homebrew default)
which python3                  # /opt/homebrew/bin/python3
brew install python@3.12       # Install specific version
poetry shell                   # Project environment

🐧 Linux Quick Commands:

python3 --version              # System Python (varies by distro)
which python3                  # /usr/bin/python3  
sudo apt install python3-pip   # Install pip if missing
poetry shell                   # Project environment

These guides provide professional-grade Python environments for both macOS and Linux that many senior developers would be proud to have.