pyenv ile Birden Fazla Python Sürümünü Aynı Sistemde Yönetme

Bir sunucuda Python 2.7, 3.8, 3.11 ve 3.12 aynı anda kurulu olması gerektiğinde ne yaparsınız? Sistem paket yöneticisi genellikle tek bir Python sürümünü “varsayılan” olarak ayarlar ve bu durum projelerin birbirinin ayağına basmasına neden olur. İşte tam bu noktada pyenv devreye giriyor. pyenv, birden fazla Python sürümünü yan yana kurmanızı, proje bazında farklı sürümler belirlemenizi ve sistem Python’una hiç dokunmadan çalışmanızı sağlayan şık bir araç.

pyenv Nedir ve Neden Kullanmalısınız?

pyenv, temel olarak shell’in PATH değişkenini manipüle ederek hangi Python binary’sinin çalışacağını kontrol eden hafif bir araçtır. Sistem Python’u ile hiçbir çakışma yaratmaz, root yetkisi gerektirmez ve her kullanıcı kendi Python ortamını bağımsız olarak yönetebilir.

Özellikle şu senaryolarda pyenv hayat kurtarır:

• Farklı Python sürümleri gerektiren birden fazla projeniz varsa
• Sistem Python’unu bozmadan denemeler yapmak istiyorsanız
• CI/CD pipeline’larında belirli Python sürümlerini test etmeniz gerekiyorsa
• Bir takımda herkesin aynı Python sürümünü kullanmasını zorunlu kılmak istiyorsanız
• Legacy bir projeyi Python 3.8’de, yeni bir projeyi 3.12’de çalıştırmanız gerekiyorsa

Kurulum Öncesi Gereksinimler

pyenv, Python’u kaynaktan derlediği için bazı bağımlılıklara ihtiyaç duyar. Ubuntu/Debian tabanlı sistemlerde şunları kurmanız gerekir:

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 libxml2-dev libxmlsec1-dev 
libffi-dev liblzma-dev git

RHEL/CentOS/Rocky Linux tabanlı sistemler için:

sudo dnf groupinstall "Development Tools"
sudo dnf install -y openssl-devel bzip2-devel libffi-devel 
xz-devel readline-devel sqlite-devel ncurses-devel tk-devel

Bu paketleri atlamayın. Eksik bağımlılıkla kurulan Python sürümlerinde ssl, sqlite3 veya readline modülleri çalışmaz ve sonradan “ModuleNotFoundError” gibi sinir bozucu hatalarla karşılaşırsınız.

pyenv Kurulumu

En kolay kurulum yöntemi resmi installer scripti kullanmaktır:

curl https://pyenv.run | bash

Bu komut pyenv’i ve en sık kullanılan eklentileri (pyenv-update, pyenv-virtualenv) ~/.pyenv dizinine kurar. Kurulum sonrası shell yapılandırmasını güncellemeniz gerekir.

Bash kullanıyorsanız ~/.bashrc dosyasına şunları ekleyin:

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Zsh kullanıyorsanız aynı satırları ~/.zshrc dosyasına ekleyin. Değişiklikleri uygulamak için:

source ~/.bashrc
# ya da zsh kullanıyorsanız
source ~/.zshrc

Kurulumun başarılı olduğunu doğrulayın:

pyenv --version
# pyenv 2.4.x gibi bir çıktı görmelisiniz

Python Sürümlerini Kurmak

pyenv ile mevcut tüm Python sürümlerini listeleyebilirsiniz. Bu liste oldukça uzundur, bu yüzden grep ile filtreleyin:

# Tüm CPython sürümlerini listele
pyenv install --list | grep -E "^s+3.(8|9|10|11|12)"

# PyPy sürümlerini listele
pyenv install --list | grep pypy

Belirli bir sürümü kurmak için:

pyenv install 3.11.9
pyenv install 3.12.3
pyenv install 3.8.19

Kurulum sırasında Python kaynaktan derlenir, bu yüzden birkaç dakika sürebilir. Sunucu üzerinde çalışıyorsanız ve CPU sayısına göre derlemeyi hızlandırmak istiyorsanız:

MAKE_OPTS="-j$(nproc)" pyenv install 3.12.3

Kurulu sürümleri görmek için:

pyenv versions
# * system (set by /home/kullanici/.pyenv/version)
#   3.8.19
#   3.11.9
#   3.12.3

Yıldız işareti aktif olan sürümü gösterir.

Sürüm Yönetimi: Global, Local ve Shell

pyenv üç farklı seviyede Python sürümü belirlemenizi sağlar. Bu hiyerarşiyi anlamak pyenv kullanımının özüdür.

Global Sürüm

Sistemdeki varsayılan Python sürümünü belirler. Hiçbir proje veya shell düzeyinde sürüm tanımlanmadığında bu devreye girer:

pyenv global 3.11.9

# Doğrulama
python --version
# Python 3.11.9

Local Sürüm

Proje dizinine özel Python sürümünü belirler. Bu komut çalıştırıldığı dizine .python-version dosyası oluşturur:

cd ~/projelerim/eski-django-app
pyenv local 3.8.19

# .python-version dosyası oluşturuldu
cat .python-version
# 3.8.19

# Bu dizinde python çağırdığınızda
python --version
# Python 3.8.19

Bu dosyayı Git reposuna commit etmek iyi bir pratiktir. Takım arkadaşlarınız da aynı Python sürümünü otomatik olarak kullanır.

Shell Sürümü

Yalnızca mevcut terminal oturumu için geçici olarak sürüm değiştirir:

pyenv shell 3.12.3

python --version
# Python 3.12.3

# Oturumu kapatıp açtığınızda geri döner

Test senaryolarında veya hızlı denemeler yaparken çok işe yarar.

Gerçek Dünya Senaryosu: Çoklu Proje Yönetimi

Diyelim ki bir freelancer olarak üç farklı müşterinin projesinde çalışıyorsunuz:

• Müşteri A: Django 2.2 kullanan legacy bir uygulama, Python 3.8 gerektiriyor
• Müşteri B: FastAPI tabanlı modern API, Python 3.11 ile çalışıyor
• Müşteri C: Veri bilimi projesi, Python 3.12 ve en son kütüphaneleri kullanıyor

Dizin yapısını oluşturup her biri için sürümü ayarlayın:

mkdir -p ~/projeler/{musteri-a,musteri-b,musteri-c}

cd ~/projeler/musteri-a
pyenv local 3.8.19

cd ~/projeler/musteri-b
pyenv local 3.11.9

cd ~/projeler/musteri-c
pyenv local 3.12.3

# Artık dizinler arasında geçiş yaparken Python sürümü otomatik değişir
cd ~/projeler/musteri-a && python --version  # 3.8.19
cd ~/projeler/musteri-b && python --version  # 3.11.9
cd ~/projeler/musteri-c && python --version  # 3.12.3

pyenv-virtualenv ile Sanal Ortam Entegrasyonu

pyenv tek başına sürüm yönetimini çözer ama proje bazında bağımlılık izolasyonu için sanal ortamlara da ihtiyacınız var. pyenv-virtualenv eklentisi ikisini birleştirir.

Yeni bir sanal ortam oluşturmak için:

# Sözdizimi: pyenv virtualenv <python-surumu> <ortam-adi>
pyenv virtualenv 3.11.9 musteri-b-env
pyenv virtualenv 3.8.19 musteri-a-env

Sanal ortamı aktive etmek:

# Manuel aktivasyon
pyenv activate musteri-b-env

# Deaktivayson
pyenv deactivate

Daha güzel bir yaklaşım, sanal ortamı proje dizinine otomatik bağlamaktır:

cd ~/projeler/musteri-b
pyenv local musteri-b-env

# Artık bu dizine girdiğinizde ortam otomatik aktive olur
cd ~/projeler/musteri-b
python --version  # Python 3.11.9
which python      # ~/.pyenv/versions/musteri-b-env/bin/python

Tüm sanal ortamları listelemek için:

pyenv virtualenvs
# musteri-a-env (created from ~/.pyenv/versions/3.8.19)
# musteri-b-env (created from ~/.pyenv/versions/3.11.9)

pip ile Paket Yönetimi

Her sürüm ve sanal ortamın kendi pip’i vardır. Hangi pip’i kullandığınızı her zaman kontrol edin:

which pip
pip --version

Paket kurulumu her zamanki gibi çalışır:

# Aktif ortama paket kur
pip install django==4.2
pip install fastapi uvicorn

# requirements.txt'ten kur
pip install -r requirements.txt

# Kurulu paketleri dışa aktar
pip freeze > requirements.txt

pyenv Sürüm Güncelleme

pyenv’in kendisini güncellemek için (pyenv-update eklentisi kuruluysa):

pyenv update

Belirli bir Python sürümünü güncellemek için önce yeni sürümü kurun, ardından eskisini kaldırın:

# Yeni sürümü kur
pyenv install 3.11.10

# Global sürümü güncelle
pyenv global 3.11.10

# Eski sürümü kaldır
pyenv uninstall 3.11.9

Kullanmadığınız sürümleri kaldırmak disk alanı açar. Her Python sürümü derleme dosyaları dahil 300-500 MB yer kaplayabilir.

Sorun Giderme

“command not found: pyenv” Hatası

Shell yapılandırma dosyanızı kontrol edin. PATH ayarının doğru yapıldığından emin olun:

echo $PYENV_ROOT
# /home/kullanici/.pyenv çıkması lazım

echo $PATH | grep pyenv
# PATH içinde pyenv/bin görünmeli

Görünmüyorsa ~/.bashrc veya ~/.zshrc dosyasını tekrar düzenleyip source ile yükleyin.

SSL Modülü Hatası

Python kurulumundan sonra import ssl çalışmıyorsa OpenSSL geliştirme dosyaları eksik demektir. Ubuntu’da:

sudo apt install libssl-dev
pyenv uninstall 3.12.3
pyenv install 3.12.3

Derleme Hatası: “_lzma” Modülü

sudo apt install liblzma-dev
# Sonra Python sürümünü yeniden derleyin
pyenv install 3.12.3

Birden Fazla Sürümü Aynı Anda Aktif Etmek

Bazı araçlar farklı Python binary isimlerini arar. pyenv ile birden fazla sürümü eş zamanlı aktif edebilirsiniz:

pyenv global 3.12.3 3.11.9 3.8.19

# Artık hem python3.12 hem python3.11 hem python3.8 çalışır
python3.12 --version
python3.11 --version
python3.8 --version

Bu özellikle tox veya nox gibi araçlarla birden fazla Python sürümünde test çalıştırırken çok işe yarar.

macOS’ta pyenv Kullanımı

macOS’ta Homebrew üzerinden kurulum önerilir:

brew update
brew install pyenv
brew install pyenv-virtualenv

~/.zshrc dosyasına (macOS’ta varsayılan shell Zsh’tir):

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

macOS Sonoma ve sonrasında Xcode Command Line Tools’un kurulu olduğundan emin olun:

xcode-select --install

CI/CD Pipeline’larında pyenv

GitHub Actions veya GitLab CI’da pyenv kullanımı için .python-version dosyasının repo’da olması yeterlidir. Örnek bir GitHub Actions workflow:

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python with pyenv version
        run: |
          PYTHON_VERSION=$(cat .python-version)
          echo "Using Python $PYTHON_VERSION"
      - uses: actions/setup-python@v5
        with:
          python-version-file: '.python-version'

Bu yapıda .python-version dosyası hem lokal geliştirme ortamında pyenv tarafından hem de CI’da actions/setup-python tarafından okunur. Versiyon tutarsızlığı problemi kökten çözülür.

pyenv’in Alternatifleri ile Karşılaştırma

Araç seçerken neye ihtiyacınız olduğunu bilmek önemlidir:

• conda: Özellikle veri bilimi için güçlüdür, hem Python hem paket yönetimini yapar ama ağır bir araçtır
• asdf: Python dışında Ruby, Node.js, Go gibi dilleri de yönetir, tek araçla her şey isteyenler için uygun
• virtualenv + manuel yönetim: Basit senaryolar için yeterli ama sürüm yönetimi yapamaz
• pyenv: Sadece Python odaklı, hafif, Unix felsefesinyle uyumlu, production sunucularında bile güvenle kullanılabilir

Sonuç

pyenv, Python geliştirme ortamlarını yönetmenin en temiz yollarından biri. Sistem Python’una dokunmadan, root yetkisi gerektirmeden ve shell entegrasyonu sayesinde dizinler arası geçişte otomatik sürüm değiştirerek çalışır.

Kurulumu bir kez yapıp .python-version dosyalarını Git repolarınıza eklediğinizde hem kendi makinenizde hem ekip arkadaşlarınızın makinelerinde hem de CI/CD pipeline’larında tutarlı bir Python ortamı sağlamış olursunuz. “Bende çalışıyor” problemini büyük ölçüde ortadan kaldırır.

Özellikle birden fazla projeyle çalışan, legacy ve modern sistemleri aynı anda desteklemesi gereken sysadmin ve geliştiriciler için pyenv vazgeçilmez bir araç haline gelir. Bir kez alıştıktan sonra nasıl yaşadığınızı sorgulatacak türden bir kolaylık sunar.