How to Install and Use pyenv on macOS

Managing multiple Python versions on your MacOS can be challenging. pyenv - a fantastic tool that lets you switch between Python versions seamlessly. In this guide, I’ll walk you through installing and using pyenv on macOS.

What is pyenv?

pyenv is a Python version management tool that allows you to:

Install multiple Python versions
Switch between them easily
Set global and project-specific Python versions
Manage virtual environments

Prerequisites

Before we begin, make sure you have:

macOS
Homebrew package manager
Terminal access

Installation Steps

1. Install Required Dependencies

First, install the required dependencies using Homebrew:

brew install openssl readline sqlite3 xz zlib

2. Install pyenv

Install pyenv using Homebrew:

brew install pyenv

3. Configure Your Shell

Add pyenv to your shell configuration. If you’re using zsh (default in modern macOS), add these lines to your ~/.zshrc:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

If you’re using bash, add the same lines to ~/.bash_profile or ~/.bashrc.

Restart your terminal or reload your shell configuration:

source ~/.zshrc  # or source ~/.bash_profile for bash

Using pyenv

List Available Python Versions

To see all available Python versions:

pyenv install --list

Install a Python Version

To install a specific Python version:

pyenv install 3.9.7

List Installed Versions

View your installed Python versions:

pyenv versions

Set Global Python Version

Set a default Python version for your system:

pyenv global 3.9.7

Set Local Python Version

Set a Python version for a specific project directory:

cd your-project
pyenv local 3.8.12

Check Current Python Version

Verify your active Python version:

python --version
pyenv version

Working with Virtual Environments

pyenv works great with virtual environments. Here’s how to use them:

Install pyenv-virtualenv

brew install pyenv-virtualenv

Add to your shell configuration:

echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc

Create a Virtual Environment

pyenv virtualenv 3.9.7 my-project-env

Activate/Deactivate Environment

# Activate
pyenv activate my-project-env
# Deactivate
pyenv deactivate

Common Issues and Solutions

1. Python Build Fails

If you encounter build failures, ensure you have all required dependencies:

brew install openssl readline sqlite3 xz zlib

2. Command Not Found

If pyenv commands aren’t recognized, verify your shell configuration and restart your terminal.

Best Practices

Always use virtual environments for projects
Keep your pyenv installation updated
Document Python versions in your projects
Use .python-version files for project-specific versions

Conclusion

pyenv is an invaluable tool for Python development on macOS. It simplifies version management and helps maintain clean, isolated development environments. With this setup, you can easily switch between Python versions and manage project-specific environments.

Remember to periodically update pyenv and your Python versions to ensure you have the latest features and security updates.

Happy coding! 🐍✨

This guide was last updated: 06 November, 2024