15 Feb 2026

pyenv

A quick guide to using pyenv for managing multiple Python versions on macOS, with industry best practices for development.

python pyenv macos development industry

Pyenv is an essential tool for Python developers, especially when working on multiple projects that require different Python versions. It allows you to easily switch between versions and maintain project-specific environments without affecting your system Python. Some key benefits of using pyenv include:

• Manage multiple Python versions (3.8, 3.9, 3.10, 3.11 etc.)
• Maintain project-specific environments
• Avoid breaking system Python
• Ensure team-wide version consistency

Frequently Used Commands

• pyenv install -l List all available Python versions for installation
• pyenv install <version> Install a specific Python version
• pyenv global <version> Set the global default Python version
• pyenv local <version> Set a Python version for the current project
• pyenv shell <version> Temporarily switch Python version for the current shell session
• pyenv --version Display the currently active Python version
• pyenv which python Show the path to the currently active Python executable
• pyenv uninstall <version> Uninstall a specific Python version
• pyenv rehash Rebuild the shims after installing/uninstalling versions

---

Why Use `pyenv local` Inside Each Project?

When you have multiple projects, each may require a different Python version. Using pyenv local allows you to set a specific Python version for each project without affecting others.

pyenv local 3.11.7

What it does:

• Creates a file named .python-version inside your project folder.
• This file stores the Python version for that project.

Effect:

• Whenever you enter that folder, pyenv automatically switches to Python 3.11.7.
• Different projects can use different Python versions.
• No version conflicts between projects.
• Teams maintain consistency.

Why Combine With Virtual Environment (venv)?

Even if two projects use the same Python version,
their installed packages may differ.

Example:

• Project A → Django 4
• Project B → Django 5

To avoid package conflicts:

python -m venv venv  
source venv/bin/activate  

Explanation:

python -m venv venv Creates a private isolated environment folder named venv.

source venv/bin/activate Activates that isolated environment.

After activation:

• pip install installs packages only inside this project.
• No global pollution.
• Other projects remain unaffected.

Combined Industry Command Explained

pyenv install 3.11.7 && pyenv local 3.11.7 && python -m venv venv

Step-by-step:

1. Installs Python 3.11.7
2. Sets that version only for the current project
3. Creates an isolated virtual environment

This gives:

• Version isolation (via pyenv)
• Dependency isolation (via venv)

Standard Project Structure

my-project/
|– .python-version
|– venv/
|– app.py
|– requirements.txt

Every project has:

• Its own Python version
• Its own dependencies
• No global conflicts