Python Version Manager: Guide To Multiple Python Versions

Have you ever had a project that required an older version of Python while your machine is running a newer one? You’re not alone – managing multiple Python versions can be a headache for developers. Luckily, pyenv makes it easy to switch between Python versions without conflicts. In this beginner-friendly tutorial, we’ll show you step-by-step how to install and use this Python version manager on any OS, so you can seamlessly work with different Python versions.

Why You Need a Python Version Manager?

Python is constantly evolving. Every few months, a new version drops with shiny features (and sometimes breaking changes). That’s great for innovation, but it’s a nightmare when you’re juggling projects with different version requirements. One project needs Python 3.7, another wants Python 3.10, and that random script you downloaded? Yeah, it only works with Python 2.7.

Without a tool like PyEnv, your system Python setup can become a chaotic mess. Worse, you might break critical tools or apps. Managing Python versions isn’t just a convenience—it’s survival.

Here’s what good version management lets you do:

Project Isolation: Keeps your projects separate and prevents dependency conflicts. This is huge.

Testing: Allows you to test your code against multiple Python versions to ensure compatibility.

Flexibility: Gives you the freedom to use the right Python version for the job.

Pro Tip 💡: Learn to set up your python local environment the right way.

Meet pyenv: Your Ultimate Python Version Manager

Now, there are several tools for Python version management, but my personal favourite is pyenv, and the one we’ll be focusing on this today. It’s lightweight, easy to use, and works like a charm on macOS and Linux. (Windows users might consider pyenv-win, which is a port).

Think of pyenv as your Python version remote control. Here’s a simple to understand flow diagram how a python version manager like pyenv roughly works:

Ready to get your hands dirty? Let’s get pyenv set up on your machine.

Setting Up pyenv (Step-by-Step Tutorial)

1. How To Install pyenv

First, we need to install PyEnv. The method varies depending on your OS, but I’ve got you covered.

On macOS or Linux:

Run the following commands in your terminal:

curl https://pyenv.run | bash  

curl https://pyenv.run | bash  

This downloads and sets up PyEnv. Simple, right?

If you are a macOS homebrew user, you can use:

brew update
brew install pyenv

brew update
brew install pyenv

On Windows:

For Windows folks, grab PyEnv-win. Install it using this command on PowerShell:

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

2. Configure path for your python version manager

Next, update your shell configuration to recognize PyEnv. For macOS/Linux, add these lines to your .bashrc or .zshrc:

 echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
 echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
 echo 'eval "$(pyenv init -)"' >> ~/.zshrc  

 echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
 echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
 echo 'eval "$(pyenv init -)"' >> ~/.zshrc  

Now, restart your terminal, and you’re good to go.

3. Using Pyenv: Install Python Versions

Now, the fun part is installing Python! Let’s say you need Python 3.9. Just run:

pyenv install 3.9.16

pyenv install 3.9.16

Need Python 2.7 for legacy reasons? No problem:

pyenv install 2.7.18

pyenv install 2.7.18

You can see all available versions with pyenv install --list.

4. Set a Global Python Version

To set a default version system-wide, use:

pyenv global 3.9.16  

pyenv global 3.9.16  

Boom. Now, whenever you type python in your terminal, it’ll use Python 3.9.16.

5. Use Per-Project Local Version

Here’s the magic: you can set a specific version with the Python version manager just for a specific project. Navigate to your project directory and run:

pyenv local 3.8.10  

pyenv local 3.8.10  

This creates a .python-version File in the project folder. PyEnv will automatically switch to Python 3.8.10 whenever you’re in that directory and trying to use the python command. Check the current version: python --version. You should see Python 3.8.10

6. Verify Your Setup

Check which Python version is active with:

pyenv version  

pyenv version  

And list all installed versions:

pyenv versions  

pyenv versions  

If everything looks good, you’re all set!

7. Activate virtual environment for the project

python -m venv venv
source venv/bin/activate

python -m venv venv
source venv/bin/activate

Pro Tip: Learn more in-depth about working with Python virtual environments.

Common Python Version Manager Troubleshooting Tips

Let’s face it—things don’t always go smoothly. Here are a few hiccups you might hit and how to fix them.

• Problem: pyenv Command not found.
  Fix: Double-check your shell configuration. Did you add pyenv to your PATH as per step 1 above? Make sure you sourced your .bashrc or .zshrc file as well.
• Problem: Python build fails during installation.
  Fix: Install the required build dependencies. For Ubuntu, run:sudo apt update && sudo apt install -y make build-essential libssl-dev zlib1g-dev
• Problem: PyEnv and virtual environments are confusing.
  Fix: Combine PyEnv with PyEnv-Virtualenv for managing virtual environments easily.

Limitations of pyenv

PyEnv is awesome, but it’s not perfect. Here are some quirks:

• Compatibility: Not every Python version might be available on every system. You can check the available versions using pyenv install -l the command.
• Performance: Managing multiple versions can use more disk space and might slow down your shell’s startup time. Additionally, switching versions can be slightly slower with tools like Docker for isolated environments.
• Learning Curve: Setting it up takes slight effort, as we saw in this article, especially if you’re new to Python.

But once you get the hang of it, these downsides are small potatoes compared to the benefits.

Final Thoughts

pyenv saved my sanity, and I hope it does the same for you. Managing Python versions used to feel like wrangling cats. Now? It’s a two-second job.

Start small. Install pyenv, Try switching between versions, and use it for your next project. Before you know it, you’ll wonder how you ever coded without it.

So, what are you waiting for? Go install PyEnv and take control of your Python versions today. Trust me, your future self will thank you.

Got questions? Drop them in the comments below, or check out the official pyenv GitHub readme.

Python Version Manager FAQs