How to Install Pyenv on Ubuntu (2026 Guide) – Manage Multiple Python Versions Like a DevOps Pro

Introduction

Managing Python versions in production environments is one of the most overlooked yet critical skills for developers and DevOps engineers. If you're working with Django, FastAPI, or AI/ML applications, using the wrong Python version can break your entire system.

In this complete guide, you will learn how to install Pyenv on Ubuntu, manage multiple Python versions safely, and follow real-world DevOps best practices.

Real DevOps Story: A Costly Python Mistake

In one real production incident, a developer installed a Python package globally using sudo pip install. This unintentionally upgraded a system dependency required by Ubuntu’s package manager. Within minutes, critical services stopped working, including apt and automation scripts.

The downtime lasted hours, and the fix required rebuilding the server.

This is exactly where Pyenv becomes essential.

What is Pyenv and Why You Should Use It?

Pyenv is a simple yet powerful tool that allows you to install and switch between multiple Python versions without affecting your system.

• System Protection: Keeps Ubuntu Python untouched
• Version Control: Install multiple Python versions easily
• Project Isolation: Different projects, different versions
• DevOps Ready: Works with Docker, CI/CD pipelines

Step 1: Update Ubuntu System

Always start by updating your system:

sudo apt update && sudo apt upgrade -y

If you face errors during update (like rate limits), read this guide: Fix 429 Too Many Requests Error in Ubuntu apt update

Step 2: Install Required Dependencies

Pyenv compiles Python from source, so install the required packages:

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

Step 3: Install Pyenv

sudo curl https://pyenv.run | bash

Configure Environment

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

source ~/.bashrc

Step 4: Install Python Version

pyenv install 3.10.14
pyenv global 3.10.14

Step 5: Use Project-Specific Python Version

sudo mkdir my-python-project && cd my-python-project
pyenv local 3.10.14

This creates a .python-version file and ensures consistency across environments.

Common Permission Error (Important Fix)

If you see this error:

pyenv local 3.10.14
/home/itadmin/.pyenv/libexec/pyenv-version-file-write: line 37: .python-version: Permission denied

This happens when your project folder is owned by root or created using sudo.

Fix it using:

sudo chown -R $USER:$USER ~/my-python-project

Then run again:

pyenv local 3.10.14

Best Practices for Production (DevOps Tips)

• Never use sudo with pyenv commands.
• Always use exact Python versions (e.g., 3.10.14)
• Never use sudo pip install
• Use pyenv local for each project
• Combine Pyenv with virtual environments
• Document Python versions in README or deployment scripts

Common Errors and Fixes

Internal Resources (Recommended Guides)

To improve your DevOps workflow, check out these related guides:

• How to Deploy FastAPI on Ubuntu (Production Guide)

Frequently Asked Questions (FAQ)

1. Is Pyenv safe for Ubuntu?

Yes, Pyenv is completely safe because it installs Python versions in your user directory and does not modify system Python.

2. Can I use Pyenv in production servers?

Yes. Many DevOps engineers use Pyenv in staging and production environments, especially in CI/CD pipelines and Docker builds.

3. What is the difference between Pyenv and virtualenv?

Pyenv manages Python versions, while virtualenv creates isolated environments for dependencies. Both should be used together.

4. Why does Pyenv build Python from source?

Building from source ensures compatibility with your system and allows better performance optimization.

5. How do I uninstall Pyenv?

You can remove Pyenv by deleting the ~/.pyenv directory and removing configuration lines from .bashrc.

6. Can I install multiple Python versions?

Yes, you can install unlimited versions and switch between them easily using Pyenv.

Conclusion

You now understand how to install Pyenv on Ubuntu and manage Python versions like a professional DevOps engineer. This approach ensures stability, scalability, and clean system management.

By following these practices, you avoid common production issues and build reliable Python-based systems.