Manage Multiple Python Versions on Ubuntu with Pyenv
Pyenv on Ubuntu: Install, Switch, and Manage Multiple Python Versions (Safely)
A practical, copy-paste friendly guide to installing pyenv, building Python versions, and keeping system Python untouched.
Ubuntu ships with a “system Python” that OS tools rely on. Replacing or altering it can break package managers and system utilities. pyenv solves this by installing additional Python versions under your home directory and switching between them via lightweight shims—so your OS stays safe while your projects stay reproducible.
๐ What You’ll Learn
- → How pyenv works (shims + version selection)
- → Installing pyenv on Ubuntu (recommended method)
- → Installing a specific Python version and setting it globally/locally
- → Best practices: virtual environments, upgrades, and troubleshooting
1. Why pyenv (and why not replace system Python)
On Ubuntu, the system Python may be used by OS components and package tooling. pyenv installs additional Pythons under
~/.pyenv and selects them by updating your PATH to point at pyenv’s
shims first.
✅ What you get
- ✓ Multiple Python versions side-by-side (per user, no sudo)
-
✓
Project-specific versions via
.python-version - ✓ Simple switching: global, local, or shell session
⚠️ What to avoid
- • Don’t remove/replace Ubuntu’s system Python packages
-
•
Don’t rely on
sudo pipfor system installs
2. Install build dependencies (Ubuntu)
pyenv builds CPython from source, so you’ll need compilers and common libraries. Run:
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 \
libffi-dev liblzma-dev
If you later hit build errors (OpenSSL, zlib, bz2), revisit this step—missing system libraries are the #1 cause of
pyenv install failures.
3. Install pyenv
The official installer script downloads pyenv and common plugins into ~/.pyenv.
It does not automatically edit your shell files—you’ll do that in the next step.
curl -fsSL https://pyenv.run | bashPrefer not to pipe to bash? You can also install from the official GitHub repo; see references at the end.
4. Configure your shell (Bash / Zsh)
You need two things: put pyenv on PATH, and initialize it so the shims work. Add the snippet below to the appropriate file(s) for your shell.
Bash (Ubuntu default)
Add to ~/.bashrc:
export PYENV_ROOT="$HOME/.pyenv"
[[ -d "$PYENV_ROOT/bin" ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"
For login shells, also ensure PATH is set early (often ~/.profile on Ubuntu):
export PYENV_ROOT="$HOME/.pyenv"
[[ -d "$PYENV_ROOT/bin" ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"Zsh
Add to ~/.zshrc:
export PYENV_ROOT="$HOME/.pyenv"
[[ -d "$PYENV_ROOT/bin" ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"
Restart your terminal (or run source ~/.bashrc) and verify:
pyenv --version
pyenv root5. Install a Python version (example: Python 3.12)
First, list available versions and pick the exact patch release you want:
pyenv install --list | grep -E "^\s*3\.12\."
Then install one of the listed versions (replace 3.12.x with a real value from your list):
pyenv install 3.12.x6. Switch Python versions (global / local / shell)
๐ Global
Default for your user account.
pyenv global 3.12.x
python --version๐ Local (per project)
Writes .python-version in the folder.
cd your/project
pyenv local 3.12.x⏱️ Shell (this terminal only)
Temporary override for the current session.
pyenv shell 3.12.x
Use pyenv versions to see what’s installed and what’s active.
7. Best practice: use virtual environments
pyenv selects the Python interpreter. For project dependencies, still use an isolated environment:
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip๐ง Tip: keep it predictable
Commit .python-version (pyenv) and a dependency lock strategy
(requirements.txt, poetry.lock, etc.)
so teammates and CI use the same interpreter and packages.
8. Troubleshooting common pyenv install issues
“python-build: error: … OpenSSL / zlib / bz2 …”
Re-check the Ubuntu build dependencies from Step 2. Missing libssl-dev,
zlib1g-dev, or libbz2-dev
is very common.
“pyenv: command not found”
Your shell isn’t loading pyenv yet. Confirm you added the init snippet to the right file, then restart the terminal.
Also run echo $SHELL to confirm whether you’re using bash or zsh.