Pyenv Deployment and Usage Guide

Prerequisites

Before installing pyenv, ensure your system has the necessary build tools and dependencies for compiling Python:

Linux/UNIX: Install development tools and libraries

# Ubuntu/Debian
sudo apt-get 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

# CentOS/RHEL
sudo yum install -y gcc zlib-devel bzip2 bzip2-devel readline-devel \
  sqlite sqlite-devel openssl-devel tk-devel libffi-devel

macOS: Install Xcode Command Line Tools
```
xcode-select --install
```
Windows: Windows is not officially supported. Use WSL (Windows Subsystem for Linux) or a virtual machine.

Installation

A. Getting Pyenv

Linux/UNIX

1. Automatic Installer (Recommended)

curl -fsSL https://pyenv.run | bash

2. Basic GitHub Checkout

# Clone pyenv to ~/.pyenv
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

# Optionally compile dynamic Bash extension
cd ~/.pyenv && src/configure && make -C src

macOS

Homebrew (Recommended)

# Update Homebrew and install pyenv
brew update
brew install pyenv

# To install development head instead of latest release
brew install pyenv --head

Configuration

B. Set up your shell environment for Pyenv

Add the following lines to your shell configuration file (~/.bashrc, ~/.zshrc, ~/.bash_profile, or ~/.profile):

For Bash:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

For Zsh:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

For Fish:

set -Ux PYENV_ROOT $HOME/.pyenv
fish_add_path $PYENV_ROOT/bin
pyenv init - | source

C. Restart your shell

exec "$SHELL"

Build & Run

Install additional Python versions

# Install a specific Python version
pyenv install 3.11.4

# Install the latest Python 3 version
pyenv install 3.11.4

# Install multiple versions
pyenv install 3.9.16
pyenv install 3.8.18

Switch between Python versions

Set global Python version:

pyenv global 3.11.4

Set local (project-specific) Python version:

cd my-project
pyenv local 3.9.16

Set shell-specific Python version:

pyenv shell 3.8.18

Check current Python version:

python --version

Deployment

Pyenv is primarily a development tool for managing Python versions locally. For deployment:

Development: Use pyenv to manage Python versions on your local machine
Production: Deploy using your platform's native Python installation or containerization (Docker)
CI/CD: Configure your CI system to use the required Python version

Docker Example:

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Copy requirements and install
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Run application
CMD ["python", "app.py"]

Troubleshooting

Common Issues and Solutions

1. "pyenv: command not found"

Ensure pyenv is in your PATH
Restart your shell after configuration
Check that eval "$(pyenv init -)" is in your shell config

2. "python: command not found" after installing Python

Run pyenv rehash to update shims
Verify the Python version is installed: pyenv versions

3. Permission denied when installing Python

Ensure you have necessary build tools installed
Try installing as a non-root user

4. "zipimport.ZipImportError: can't decompress data"

Update your system's unzip utility
Try reinstalling the Python version: pyenv uninstall 3.11.4 && pyenv install 3.11.4

5. Homebrew doctor warnings about config scripts

# Add this alias to your shell config
alias brew='env PATH="${PATH//$(pyenv root)\/shims:/}" brew'

6. pyenv not working in new shell sessions

Ensure eval "$(pyenv init --path)" is in your shell profile (not just rc file)
For macOS, add to ~/.zprofile or ~/.bash_profile

Useful Commands

# List all available Python versions
pyenv install --list

# List installed Python versions
pyenv versions

# Show current Python version
pyenv version

# Remove a Python version
pyenv uninstall 3.11.4

# Update pyenv to latest version
cd $(pyenv root) && git pull

# Check pyenv status
pyenv doctor

Advanced Configuration

Environment Variables:

# Custom pyenv root
export PYENV_ROOT="/opt/pyenv"

# Custom Python build directory
export PYTHON_BUILD_CACHE_PATH="/tmp/python-build"

Using pyenv without shims:

# Use full path to pyenv Python
$(pyenv root)/versions/3.11.4/bin/python

How to Deploy & Use pyenv/pyenv