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