Skip to content

pyenv ile Çoklu Python Sürümü Yönetimi: Sürümler Arası 'Anahtar' Olma Sanatı

Bir projende 3.10, başka projende 3.13 lazım. CI'da 3.11 test ediyorsun. Production'da 3.12. Bunların hepsini tek Linux/macOS makinende sürdürmek pyenv ile saniyeler meselesi. Bu ders pyenv'in tüm komutlarını, .python-version dosyasını, virtualenv plugin'ini ve gerçek senaryolarını işliyor.

Şükrü Yusuf KAYA
20 min read
Beginner
pyenv ile Çoklu Python Sürümü Yönetimi: Sürümler Arası 'Anahtar' Olma Sanatı
🔑 Bu dersin değeri
Bir profesyonel Python geliştiricisi nereden tanınır? Bilgisayarında 4-5 Python sürümü olur, her projede otomatik doğrusu seçilir, asla 'bu makinede çalışmıyor' demez. Bu dersi bitirdiğinde — sen de o seviyede olacaksın.

"Niye sürüm yöneticisi?" — gerçek hayattan 3 senaryo#

Önce ihtiyacı somut hisset. Aşağıdakilerden en az birini yaşayacaksın (büyük ihtimalle hepsini):

Senaryo 1: Eski projeye bakım#

Şirketinde 5 yıl önce yazılmış bir Python servisi var. Python 3.7 ile yazılmış. Bağımlılıklar 3.7'ye pin'lenmiş. Senin Mac'inde Python 3.13 kurulu — aynı projeyi clone edersen
pip install -r requirements.txt
patlıyor (bazı eski paketler 3.13 ile uyumsuz). Ne yapacaksın?
Çözüm:
pyenv install 3.7.17
, sonra proje klasörüne
pyenv local 3.7.17
deyince otomatik o klasörde Python 3.7 aktif olur. Diğer projelerinde 3.13 kalmaya devam eder.

Senaryo 2: CI'da farklı sürümler test etmek#

Açık kaynak bir Python kütüphanesi yazıyorsun (veya iş projelerinde test matrix'i var). "Python 3.10, 3.11, 3.12, 3.13'te çalışıyor" demek istiyorsun. Lokalde her sürümü kurup test etmen gerek.
Çözüm:
pyenv install 3.10.13 3.11.10 3.12.7 3.13.0
— dört sürümü yükle. Sonra
pytest
runner'ını her birinde döndür. tox veya nox ile bu otomatize.

Senaryo 3: Bağımlılığın eski Python'da#

Bir AI kütüphanesi (örnek: belirli bir TensorFlow sürümü) henüz Python 3.13'ü desteklemiyor. Senin makinende 3.13 default. O kütüphaneyi denemek istiyorsun.
Çözüm:
pyenv install 3.11.10
, deneme klasörü yarat, içinde
pyenv local 3.11.10
,
pip install tensorflow==X.Y.Z
. İşin bitince proje klasöründen çıkıp diğer işine devam — ana Python'un hâlâ 3.13.
Bu üç senaryonun hepsi pyenv olmadan ya çok zor ya imkansız. pyenv olunca — komut başına 5 saniye iş.

pyenv aslında nasıl çalışıyor?#

Anlamak için 30 saniye verelim. pyenv'in tek bir sihri var: shims.
Senin
PATH
'te
~/.pyenv/shims
adında bir klasör en başta. İçinde
python
,
python3
,
pip
,
pip3
,
pytest
,
black
... gibi yüzlerce dosya var. Hepsi shell script.
python
yazdığında shell, sırasıyla PATH'i tarıyor. İlk bulduğu yer
~/.pyenv/shims/python
oluyor. Bu shim script şunu yapıyor:
  1. Hangi sürümün aktif olduğunu anlıyor (
    .python-version
    dosyasına,
    PYENV_VERSION
    env var'a,
    pyenv global
    ayarına bakarak).
  2. Anladığı sürümün gerçek binary'sine yönlendiriyor — örn
    ~/.pyenv/versions/3.13.0/bin/python
    .
  3. Senin gözüne hiçbir şey görünmüyor — sanki direkt python çalışmış.
Yani pyenv aslında bir router. Hangi Python'un çalışacağına o karar veriyor.
# Shim'in nasıl bir dosya olduğunu görmek için
cat $(pyenv which python)   # gerçek binary path
cat ~/.pyenv/shims/python   # shim script
Bu mimari neden iyi? Çünkü PATH'i değiştirmen gerekmiyor. Bütün araçlar normal PATH'le çalışıyor; pyenv arada görünmez bir katman.
# Homebrew ile (en kolay yol)
brew install pyenv

# Shell init (zsh için, .zshrc'ye)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# Yeniden yükle
source ~/.zshrc

# Doğrula
pyenv --version
# pyenv 2.4.X
Bash kullanıcısı için:
.zshrc
yerine
.bash_profile
(macOS bash login shell)

Temel komutlar — günlük kullanım#

pyenv'in kullanacağın 80%'i sadece bu komutlar:
# 1. Hangi sürümler kuruluyor olabilir?
pyenv install --list
# (uzun bir liste — Python 3.6'dan en yenisine kadar her sürüm + PyPy + MicroPython)

# Liste filtreli
pyenv install --list | grep "^  3.13"
# Çıktı:
#   3.13.0
#   3.13.1
#   3.13.2
#   ...

# 2. Bir sürümü kur (5-10 dakika sürer; PGO build)
pyenv install 3.13.0

# 3. Hangileri kurulu?
pyenv versions
# Çıktı:
# * system (set by /Users/me/.pyenv/version)
#   3.10.13
#   3.11.10
#   3.12.7
#   3.13.0

# 4. Global default ayarla
pyenv global 3.13.0
python --version   # Python 3.13.0

# 5. Bir proje klasörü için sürüm pin'le
cd ~/projects/old-app
pyenv local 3.10.13
# Bu klasörde .python-version dosyası oluştu
cat .python-version
# 3.10.13

# Şimdi bu klasörde python = 3.10.13, dışında 3.13.0
python --version
# Python 3.10.13

cd ..
python --version
# Python 3.13.0

# 6. Sadece geçerli shell için sürüm değiştir
pyenv shell 3.11.10
# Sadece bu terminal session boyunca 3.11

# 7. Bir sürümü kaldır
pyenv uninstall 3.10.13
Bu 7 komut günlük iş akışının %95'ini kapsar.

.python-version
dosyası — magic#

pyenv local 3.10.13
çalıştırdığında pyenv senin proje klasörüne
.python-version
adında küçük bir dosya yazıyor. İçinde sadece sürüm numarası var:
$ cat .python-version
3.10.13
Bu dosya ne yapıyor? Sen o klasöre
cd
ettiğinde, pyenv shim'i otomatik bu dosyayı arıyor; bulursa o sürümü aktif ediyor. Çıktığında — ana sürümüne geri dönüyor.
Bu dosyayı git'e ekle:
# Git ile takım çalışması için
git add .python-version
git commit -m "Pin Python version to 3.10.13"
Takım arkadaşların bu repo'yu klonladığında, otomatik olarak doğru Python sürümüyle çalışacak. "Bende çalışıyor" sorununun büyük bir kısmı bu dosyayla çözülür.
Bonus:
.python-version
dosyası bir versiyon değil, birden fazla da kabul edebilir:
# Çoklu sürüm (test matrix için)
echo "3.10.13" > .python-version
echo "3.11.10" >> .python-version
echo "3.12.7" >> .python-version

# Şimdi bu klasörde 3 sürüm de aktif
pyenv versions
# * 3.10.13 (set by /path/to/.python-version)
# * 3.11.10 (set by /path/to/.python-version)
# * 3.12.7 (set by /path/to/.python-version)
Bu kullanışlı mı? Tox/Nox gibi test runner'larla çoklu sürüm test ederken, evet.

Sürüm seçim önceliği — bilmen gereken#

pyenv hangi sürümü kullanacağına nasıl karar veriyor? Aşağıdaki sıraya bakıyor (yüksekten düşüğe):
  1. PYENV_VERSION
    environment variable — varsa o.
  2. Bulunduğun klasör veya yukarıdaki herhangi bir klasörde
    .python-version
    dosyası — bulduğu ilki.
  3. Global
    ~/.pyenv/version
    dosyası —
    pyenv global X
    ile yazılan.
  4. system
    Python.
# 1. yöntem: bir komut için sürüm seç
PYENV_VERSION=3.11.10 python my_script.py

# 2. yöntem: proje sürümü
echo "3.10.13" > .python-version

# 3. yöntem: global default
pyenv global 3.13.0

# Hangi sürümün aktif olduğunu ve neden
pyenv version
# Çıktı: 3.10.13 (set by /home/me/myproject/.python-version)
Bu öncelik sistemi sayesinde "bu klasörde 3.10, başka klasörde 3.13" pratik oluyor.

pyenv-virtualenv — virtualenv'i de pyenv yönetsin#

pyenv tek başına Python sürümlerini yönetiyor ama her projenin bağımlılıkları ayrı virtualenv'lerde olmalı. pyenv-virtualenv plugin'i bu ikisini birleştiriyor.

Kurulum#

# macOS
brew install pyenv-virtualenv

# Linux
git clone https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

# Shell init (.bashrc/.zshrc'ye)
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc
source ~/.zshrc

Kullanım#

# Bir Python sürümünden virtualenv yarat
pyenv virtualenv 3.13.0 my-project

# Yarattığın virtualenv'leri listele
pyenv virtualenvs
# * my-project (created from 3.13.0)
# * old-app   (created from 3.10.13)

# Bir klasöre bu virtualenv'i bağla
cd ~/projects/my-project
pyenv local my-project

# Şimdi bu klasörde python = 3.13.0 + my-project virtualenv aktif
which python
# /Users/me/.pyenv/versions/my-project/bin/python

pip install requests
# Sadece my-project virtualenv'inde

# Klasörden çıktığında virtualenv otomatik deaktif
cd ..
which python
# /Users/me/.pyenv/shims/python (default)
Bu özellik gerçekten harika:
source venv/bin/activate
yazmanı eliminiyor.
cd
'ye girince otomatik aktif, çıkınca otomatik kapalı.

Virtualenv'i sil#

pyenv virtualenv-delete my-project

Tam senaryo: 3 farklı projede 3 farklı kurulum#

Şimdi gerçek bir kullanım — dikkatlice takip et, çünkü bu pattern senin yıllarca tekrar tekrar uygulayacağın temel akış:
# === Proje 1: Eski Django app, Python 3.10, virtualenv "old-django" ===

cd ~/projects/old-django
pyenv install 3.10.13   # Eğer yüklü değilse
pyenv virtualenv 3.10.13 old-django
pyenv local old-django

pip install -r requirements.txt
# requirements.txt: Django==3.2, ...
python manage.py runserver


# === Proje 2: AI projesi, Python 3.11 (TensorFlow uyumu için), "ai-research" ===

cd ~/projects/ai-research
pyenv install 3.11.10   # Eğer yüklü değilse
pyenv virtualenv 3.11.10 ai-research
pyenv local ai-research

pip install tensorflow scikit-learn pandas numpy
jupyter lab


# === Proje 3: Yeni FastAPI servisi, Python 3.13, "api-service" ===

cd ~/projects/api-service
pyenv virtualenv 3.13.0 api-service   # 3.13.0 zaten yüklü
pyenv local api-service

pip install fastapi uvicorn pydantic sqlalchemy
uvicorn main:app --reload
Her klasöre cd ettiğinde pyenv otomatik doğru Python + doğru virtualenv'i aktif ediyor. Hiç komut yazmana gerek yok. Bir terminal'de 3 farklı tab açıp her birini farklı projeye
cd
ettiğinde — her tab kendi izole ortamında çalışıyor.
İşte profesyonel Python iş akışı bu.
bash
# Test matrix'i: aynı kütüphaneyi 4 sürümde test et
# Önce 4 sürümü yükle
pyenv install 3.10.13
pyenv install 3.11.10
pyenv install 3.12.7
pyenv install 3.13.0
 
# Proje klasöründe çoklu sürüm pin'le
cd ~/my-library
echo "3.10.13" > .python-version
echo "3.11.10" >> .python-version
echo "3.12.7" >> .python-version
echo "3.13.0" >> .python-version
 
# tox.ini: 4 sürümde test et
cat > tox.ini << 'EOF'
[tox]
envlist = py310, py311, py312, py313
 
[testenv]
deps = pytest
commands = pytest
EOF
 
# Tek komut, 4 sürümde test
pip install tox
tox
 
# Çıktı:
# py310: PASSED
# py311: PASSED
# py312: PASSED
# py313: FAILED  (... yenı sürümde yeni hata, fix lazım)
tox + pyenv kombinasyonu — açık kaynak proje yöneten herkesin standart kurulumu.

pyenv'in kendisini güncellemek#

Yeni Python sürümleri çıkıyor (örn 3.14 yakında çıkacak). pyenv'in liste'sini güncellemek için:
# Homebrew'la kurulduysan
brew update && brew upgrade pyenv

# Linux/installer ile kurulduysan
cd ~/.pyenv
git pull

# Doğrula
pyenv install --list | tail -5
# Yeni sürümler artık listede
pyenv install --list
her zaman pyenv versiyonuna bağlı. pyenv'i güncellemezsen yeni Python sürümlerini göremezsin.
Sebep: Build dependencies eksik (özellikle libssl-dev, libsqlite3-dev). pyenv aslında perde arkasında kaynaktan derliyor.
Çözüm:
# Ubuntu
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

# Fedora
sudo dnf install -y bzip2-devel openssl-devel libffi-devel \
    sqlite-devel readline-devel zlib-devel tk-devel ncurses-devel \
    gdbm-devel xz-devel
Sonra tekrar dene.

Alternatifler — pyenv tek değil#

pyenv 2010'lu yıllarda standart oldu ama 2024-2026 itibariyle alternatifler de oturmuş durumda. Hızlı bir karşılaştırma:
ToolNe yaparProCon
pyenvSadece Python sürüm yönetimiOlgun, geniş community, Linux/macOS nativeWindows desteği zayıf, kurulum kompleks
asdfÇoklu dil version manager (Python+Node+Ruby+Go...)Tek araçla her şeyi yönetPython-spesifik özellikler az
mise (rtx)asdf'in modern Rust port'uÇok hızlı, modern UXGenç (community küçük)
conda/minicondaVeri bilimi paketleri + Python sürümNumPy/pandas/Jupyter pre-bundledPython-spesifik değil; ağır
uvAstral'ın modern paket+sürüm yöneticisiÇok hızlı (Rust), tek araçSürüm yönetimi yeni eklendi (2024)
2026 önerim:
  • Hâlâ pyenv en güvenli, en olgun tercih.
  • Tek dilde çalışıyorsan ve hız önemliyse uv denenmeye değer (modül 16'da göreceğiz).
  • Çoklu dil çalışıyorsan mise (Rust) > asdf.
Bu kursta pyenv'i baz alıyoruz çünkü en yaygın ve en stabil.

Bu derste neler kazandın?#

✓ Sürüm yöneticisinin ne işe yaradığını — 3 gerçek senaryo üzerinden.
✓ pyenv'in nasıl çalıştığını — shims, PATH router mantığı.
✓ macOS, Linux, Windows kurulumu — her birine özel notlar.
✓ 7 temel komut — install, versions, global, local, shell, uninstall, rehash.
✓
.python-version
dosyasının sihrini ve takım çalışmasında değerini.
✓ Sürüm seçim önceliğini — PYENV_VERSION → .python-version → global → system.
✓ pyenv-virtualenv plugin ile auto-activate virtualenv'ler.
✓ 3 farklı projede 3 farklı kurulum senaryosu — gerçek profesyonel iş akışı.
✓ tox + pyenv test matrix'i — açık kaynak yazıyorsan standart.
✓ 6 yaygın hata ve çözümleri.
Sıradaki ders: Python REPL'i etkili kullanma. Sadece "hesap makinesi" değil — keşif ve hızlı prototipleme aracın olarak REPL'i kullanmayı öğreneceğiz. Tab completion, history,
_
operatörü, multi-line input, debugger entegrasyonu, ve "iyi geliştiricinin tek kolu" gibi olan REPL'in saklı özellikleri.

Frequently Asked Questions

İdeal pratik: **bütün Python işlerini pyenv ile yap**, sistem Python'una hiç bulaşma. pyenv kurduktan sonra `pyenv global 3.13.0` ile default'unu set edersin; günlük komutlarda farkın bile olmaz. Sistem Python işletim sistemi için kalır, sen pyenv'inle çalışırsın. Yıllar içinde edindiğim alışkanlık — hata yapmıyor, kolaylaştırıyor.

Yorumlar & Soru-Cevap

(0)
Yorum yazmak için giriş yap.
Yorumlar yükleniyor...

Related Content

Modül 1: Giriş ve Kurulum

Python Nedir, Neden Bu Kadar Popüler?

Start Learning
Modül 1: Giriş ve Kurulum

Python Sürümlerinin Tarihi: 2'den 3.14'e, AI Winter'lardan 'No-GIL' Devrimine

Start Learning
Modül 1: Giriş ve Kurulum

Python Implementasyonları: CPython, PyPy, MicroPython, Jython, IronPython, Pyodide

Start Learning