Every Python developer eventually hits the same wall: one project needs Python 3.9, another requires 3.11, and the new one won't run on anything below 3.12. The instinct is to upgrade globally — which promptly breaks something else.
There's a better way. Two tools worth knowing: pyenv and conda. They solve the same problem differently, and knowing which to reach for matters.
pyenv — Lightweight, Automatic Version Switching
pyenv lets you install and switch between Python versions at the system, user, or project level. Critically, it never touches your system Python.
Installing pyenv
Linux / Mac:
bashcurl https://pyenv.run | bash
Add this to your ~/.bashrc or ~/.zshrc:
bashexport PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
Windows — use pyenv-win:
powershellInvoke-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"
Basic Usage
bash# See available versions
pyenv install --list
Install a specific version
pyenv install 3.11.9
Set global default
pyenv global 3.11.9
Set version for current project only
pyenv local 3.10.14
pyenv local creates a .python-version file in your project directory. Every time you cd into that folder, pyenv switches automatically — no manual toggling.
Per-Project Workflow
bashcd my-project
pyenv local 3.10.14
python --version # Python 3.10.14
cd ../other-project
pyenv local 3.12.0
python --version # Python 3.12.0
Clean and automatic.
conda — Full Environment Management
conda handles Python versions and packages together. It's heavier than pyenv but earns its weight when dependencies get complex — particularly in data science and ML.
Installing conda
Download Miniconda — the minimal install — for Windows, Linux, or Mac.
Basic Usage
bash# Create an environment with a specific Python version
conda create -n myenv python=3.10
Activate it
conda activate myenv
Install packages
conda install numpy pandas
Deactivate
conda deactivate
Per-Project Workflow
bashcd my-project
conda activate project-39 # Python 3.9 environment
cd ../other-project
conda activate project-312 # Python 3.12 environment
Unlike pyenv, switching isn't automatic — you activate manually. Small trade-off for what you get in return.
pyenv vs conda — Which One?
pyenvcondaPython version switchingAutomatic (per directory)Manual activationPackage managementNo — use pip + venvYes, built-inBest forGeneral / backend / web devData science / MLWindows supportVia pyenv-win (limited)ExcellentOverheadLightweightHeavier
Use pyenv if you want lightweight, automatic version switching per project.
Use conda if you're in data science, need environment and package management together, or are primarily on Windows.
The Ideal Setup: pyenv + venv Together
For most developers, this combination covers everything:
bash# Set Python version with pyenv
pyenv local 3.11.9
Create a virtual environment
python -m venv .venv
Activate it
source .venv/bin/activate # Linux/Mac
.venv\Scripts\activate # Windows
Install dependencies
pip install -r requirements.txt
pyenv handles the version. venv handles dependency isolation. Best of both.
Common Issues Worth Knowing
pyenv: command not found after install
Your shell config wasn't reloaded. Run source ~/.bashrc (or ~/.zshrc) after editing it, or close and reopen your terminal.
conda: environment not activating in scripts
Run conda init once after installing, then restart your terminal. This adds the necessary hooks to your shell profile.
python --version still shows system Python after pyenv local
Make sure the pyenv init lines are actually in your shell config and that you've reloaded it. Running pyenv versions should list your installed versions.
Quick Reference
bash# pyenv
pyenv install 3.11.9
pyenv local 3.11.9 # project-level
pyenv global 3.11.9 # system-level
pyenv versions # list installed versions
conda
conda create -n myenv python=3.11
conda activate myenv
conda deactivate
conda env list # list all environments
Managing Python versions correctly is one of those things that saves you hours of debugging later. Set it up once, stop thinking about it.
If you're running into an issue not covered here, drop it in the comments.
Top comments (1)
Excellent guide on a common pitfall; the comparison between pyenv and virtual environments really clarifies when to use each for a stable workflow.
Your practical approach to isolating dependencies is a must-read for anyone looking to keep their local development environment clean and conflict-free.