Installing and Managing Python Versions with Pyenv on Linux, macOS, and Windows

Python version management can be tricky, especially when different projects require different Python versions. Fortunately, Pyenv makes it easy to install and switch between multiple Python versions effortlessly. This guide will walk you through installing Pyenv on Linux, macOS, and Windows, as well as troubleshooting common issues.

Installing Pyenv

📌 Linux (Ubuntu & Other Distros)

Run the following command to install Pyenv on Linux:

curl https://pyenv.run | bash

After installation, add Pyenv to your shell profile:

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

For Zsh users, replace .bashrc with .zshrc.

Reload the shell:

exec $SHELL

📌 macOS

If you’re on macOS, install Pyenv using Homebrew:

brew update
brew install pyenv

Then, add it to your shell configuration:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc

Apply the changes:

exec $SHELL

📌 Windows (Using WSL or pyenv-win)

Using Windows Subsystem for Linux (WSL)

If you have WSL (Ubuntu) installed, follow the Linux installation steps above.

Using Pyenv for Windows

For a native Windows experience, install pyenv-win:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://pyenv.run | iex

Then, add the paths to your system environment variables:

1. Open PowerShell and run:

   [System.Environment]::SetEnvironmentVariable("PYENV_ROOT", "$HOME\.pyenv", "User")
   [System.Environment]::SetEnvironmentVariable("Path", "$HOME\.pyenv\bin;$HOME\.pyenv\shims;" + [System.Environment]::GetEnvironmentVariable("Path", "User"), "User")
   

2. Restart your terminal.
3. Verify installation:

   pyenv --version
   

Installing Python with Pyenv

Once Pyenv is installed, you can use it to install specific Python versions.

For example, to install Python 3.10.12:

pyenv install 3.10.12

Set it as the global version:

pyenv global 3.10.12

Verify the installation:

python --version

To list all available Python versions:

pyenv install --list

Fixing Pyenv Load Path Issues

If you see a warning like:

WARNING: seems you still have not added 'pyenv' to the load path.

Follow these steps:

Linux/macOS

Run:

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

For Zsh, replace ~/.bashrc with ~/.zshrc.

Windows (pyenv-win)

Ensure the following paths are added to your Windows Environment Variables:

• C:\Users\YourUsername\.pyenv\bin
• C:\Users\YourUsername\.pyenv\shims

Then, restart PowerShell and try:

pyenv --version

Conclusion

Pyenv is a powerful tool for managing multiple Python versions across different platforms. Whether you're using Linux, macOS, or Windows, following the right setup ensures smooth development workflows. If you run into issues, always check your shell configuration and environment variables. 🚀

Mumuni Mohammed

Experienced DevOps Engineer proficient in Python, Docker, Kubernetes, CI/CD, and cloud technologies. Specialized in automating processes and building scalable infrastructure for seamless development and deployment.