Search for a command to run...
How to Install and Use pyenv to Manage Multiple Python Versions
Staff Engineer and technology enthusiast with over a decade of experience in building large-scale distributed systems using Java, Go, and cloud-native technologies. He writes about software engineering, system design, and developer productivity—simplifying complex tech concepts into practical insights for engineers and creators.
No comments yet. Be the first to comment.
After more than a decade in software engineering, I’ve learned something uncomfortable: The bugs that caused the most damage in production were rarely caused by bad code. They didn’t come from syntax errors, wrong loops, or missed null checks. They c...
A few weeks ago, I opened an old Python project to fix what I thought would be a quick issue. The code looked fine. The logic made sense. But the script refused to run. After a bit of digging, the problem became obvious: the project was written for P...
*What learning Go taught me about modern systems — without abandoning the language that built my career
Why developers keep declaring languages dead — and why the industry keeps proving them wrong.
When I started my tech career more than a decade ago, I thought the path was simple: Write clean code → Get promoted → Repeat. Turns out, that’s the smallest part of the job. Thirteen years later — after working across banks, stock exchanges, e-comme...
Ever worked on a project that needed Python 3.8, only to find your system default is 3.11? That’s exactly the headache
pyenvsolves — and in this guide, I’ll walk you through what it is, why you need it, and how to set it up.
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:
Here are just a few common scenarios where pyenv is a lifesaver:
sudo or messing with system-level PythonpyenvTo install and use pyenv, you'll need a few basic tools:
curl or wget: for downloading the installer scriptgit: used to clone the pyenv repository and pluginsTo install new Python versions via pyenv install, you'll also need:
gcc, makezlib, 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.
brew update
brew install pyenv
If you're on Ubuntu/Debian, you need to install manually:
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
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
pyenv install 3.10.9
pyenv local 3.8.16
This creates a .python-version file in the directory, so other tools (and your terminal) use that version automatically.
python --version
# or
pyenv version
pyenv versions aren’t being picked up, double-check your shell config and restart the terminal.pyenv doctor for environment diagnostics.pyenv which python to verify the actual Python binary being used.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.
pyenv environment persistent?Yes. Anything installed under a pyenv-managed Python version (like packages) is persistent until you remove that version.
pyenv and virtualenv?pyenv manages Python versionsvirtualenv manages dependencies for a specific projectUse both together for full isolation and version control.
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)pyenv?pyenv uninstall 3.10.9
This deletes the Python version and everything inside it.
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.
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:
pyenv global)pyenv local)Your OS will continue using its default Python version.
pyenv different from pip?pyenv manages which version of Python you're using pip installs packages for the currently active Python versionThey work together, but solve different problems.
pyenv and venv?pyenv manages Python versions venv (built-in) creates isolated virtual environmentsYou can (and should) use them together for maximum flexibility.
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:
pyenv-virtualenvpipx with pyenv for global CLI toolsDisclaimer: 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.