Mastering pyenv: The Easiest Way to Manage Multiple Python Versions

Ever worked on a project that needed Python 3.8, only to find your system default is 3.11? That’s exactly the headache pyenv solves — and in this guide, I’ll walk you through what it is, why you need it, and how to set it up.

---

🐍 What is pyenv?

pyenv is a popular tool for managing multiple Python versions on a single system. Instead of relying on the system’s Python install (which can cause conflicts), pyenv gives you full control.

It works by:

• Installing multiple Python versions side-by-side
• Letting you switch versions per project or globally
• Keeping your system Python untouched

---

❓ Why Do You Need It?

Here are just a few common scenarios where pyenv is a lifesaver:

• Your old project needs Python 3.6, but your system has 3.11
• You want to test a script across different Python versions
• You work on a team where everyone uses slightly different setups
• You want to avoid using sudo or messing with system-level Python

---

🧰 How to Install pyenv

🛠 Prerequisites

To install and use pyenv, you'll need a few basic tools:

• curl or wget: for downloading the installer script
• git: used to clone the pyenv repository and plugins

To install new Python versions via pyenv install, you'll also need:

• Compiler tools like gcc, make
• Development libraries like zlib, openssl, libffi, etc.

These are needed because pyenv builds Python from source during installation.

If you're on macOS, brew install pyenv usually handles this for you.

📦 On macOS

brew update
brew install pyenv

If you're on Ubuntu/Debian, you need to install manually:

📦 On Ubuntu/Debian

sudo apt update
sudo apt install -y make build-essential libssl-dev \
zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

curl https://pyenv.run | bash

🔁 Add to your shell config (.bashrc, .zshrc, etc.)

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Restart your terminal or run:

source ~/.zshrc  # or .bashrc

🧪 How to Use pyenv

✅ Install a Python Version

pyenv install 3.10.9

📁 Set Local Python Version for a Project

pyenv local 3.8.16

This creates a .python-version file in the directory, so other tools (and your terminal) use that version automatically.

🔍 Check Current Python Version

python --version
# or
pyenv version

🧹 Troubleshooting Tips

• If pyenv versions aren’t being picked up, double-check your shell config and restart the terminal.
• Use pyenv doctor for environment diagnostics.
• Use pyenv which python to verify the actual Python binary being used.

---

🙋 Frequently Asked Questions (FAQ)

1. Does pyenv create a kind of self-contained environment which gets destroyed after use?

Not exactly. pyenv does not create isolated or temporary environments. It installs Python versions in a central location under ~/.pyenv/versions/, and you can switch between them globally or locally.

For isolated project environments, use pyenv + pyenv-virtualenv.

---

2. Are folders or files created in a pyenv environment persistent?

Yes. Anything installed under a pyenv-managed Python version (like packages) is persistent until you remove that version.

---

3. What’s the difference between pyenv and virtualenv?

• pyenv manages Python versions
• virtualenv manages dependencies for a specific project

Use both together for full isolation and version control.

---

4. Can I use pyenv with tools like poetry, pipenv, or pipx?

Yes. Once configured, pyenv integrates seamlessly with tools like:

• poetry (for package management)
• pipenv (for environment + dependency management)
• pipx (for installing CLI tools)

---

5. How do I uninstall a Python version installed by pyenv?

pyenv uninstall 3.10.9

This deletes the Python version and everything inside it.

---

6. Does pyenv interfere with system Python?

No. It overrides Python at the shell level only. Your system's original Python version remains untouched and is still used by OS-level tasks.

---

7. If I install a Python version using pyenv, does it change the base version system-wide?

No. pyenv does not change the system-wide Python version. It only changes the Python version in your shell sessions, based on:

• Global setting (pyenv global)
• Local project setting (pyenv local)

Your OS will continue using its default Python version.

---

8. How is pyenv different from pip?

• pyenv manages which version of Python you're using
• pip installs packages for the currently active Python version

They work together, but solve different problems.

---

9. What is the difference between pyenv and venv?

• pyenv manages Python versions
• venv (built-in) creates isolated virtual environments

You can (and should) use them together for maximum flexibility.

---

📌 Final Thoughts

pyenv is one of those tools that saves you hours of frustration once you start using it. If you're working across Python projects, experimenting with frameworks, or just want a clean setup — this tool is a must-have.

In upcoming posts, I’ll explore:

• Creating virtual environments with pyenv-virtualenv
• Using pipx with pyenv for global CLI tools
• Managing Python in CI environments

---

Disclaimer: Parts of this article were refined with the assistance of AI tools to improve clarity and structure. All technical insights and perspectives are my own.