Setup Python on macOS with pyenv and venv

Why pyenv + venv?

If you're already familiar with venv for creating virtual environments, combining it with pyenv is the natural upgrade path. This setup gives you the best of both worlds:

• pyenv handles which Python version to use system-wide or per-project
• venv manages isolated environments for your project dependencies (as you already do)

This approach is more flexible than using the system Python and safer than modifying /usr/bin/python3 (which you should never delete as it's an Apple stub used by macOS and tools like Homebrew).

Installation

Installing pyenv on macOS is straightforward with Homebrew:

brew install pyenv

Configuration

After installation, you need to add pyenv to your shell configuration. Add the following lines to your ~/.zshrc file:

eval "$(pyenv init --path)"
eval "$(pyenv init -)"

Then reload your shell configuration:

source ~/.zshrc

Common Commands

Install a Python Version

To install a specific Python version (e.g., Python 3.12.9):

pyenv install 3.12.9

List Installed Versions

To see all Python versions you have installed:

pyenv versions

Set Global Default Version

To set a Python version as your system-wide default:

pyenv global 3.12.9

Set Local Version for a Project

To pin a specific Python version for your current project:

cd /path/to/your/project
pyenv local 3.11.8

This creates a .python-version file in your project directory. When you cd into this directory, pyenv automatically switches to the specified Python version.

Using venv (As Usual)

Once pyenv is configured and you've set your desired Python version, you can use venv exactly as you're used to:

# Create a virtual environment
python -m venv .venv

# Activate it
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Deactivate when done
deactivate

Complete Workflow Example

Here's a typical workflow for starting a new Python project:

# Create project directory
mkdir my-new-project
cd my-new-project

# Set Python version for this project
pyenv local 3.12.9

# Verify the Python version
python --version
# Output: Python 3.12.9

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Install packages
pip install requests flask

# Generate requirements file
pip freeze > requirements.txt

# Your Python environment is ready!
python app.py

Important Safety Note

Quick Reference Table

Troubleshooting

Command Not Found: pyenv

If you get "command not found" after installing pyenv, make sure you've:

1. Added the initialization lines to your ~/.zshrc
2. Reloaded your shell with source ~/.zshrc

Python Version Not Changing

If the Python version doesn't change after running pyenv local or pyenv global:

1. Check that pyenv is properly initialized in your shell
2. Verify the version is installed with pyenv versions
3. Try opening a new terminal window

Conclusion

The combination of pyenv and venv gives you professional-grade Python version management while keeping your familiar venv workflow. You get:

• Multiple Python versions installed side-by-side
• Easy switching between versions globally or per-project
• Isolated project dependencies with venv
• No interference with system Python

This setup scales from small scripts to large production applications, making it the go-to choice for Python development on macOS.