Sanal ortam ve paket yönetimi

Derinleş: Kurulumdan kilit dosyasına paket yönetimi

Bu bölüm bir başvuru kılavuzudur: her işletim sisteminde sanal ortamı kurup etkinleştirme, pip'in tüm günlük komutları, requirements ve constraints dosyaları, pip-tools, uv, poetry, conda ve pipx ile iş akışları ve en sık karşılaşılan hataların çözümü. Komutları kendi bilgisayarında, proje klasöründe dene; tarayıcıdaki örnekler ise ortamı ve sürümleri Python'dan nasıl sorgulayacağını gösterir. Altın kural: pip yerine python -m pip yaz; böylece paket, o an çalışan Python'a kurulur.

1. venv: her işletim sisteminde oluştur, etkinleştir, doğrula

Etkinleşince istemde (prompt) (.venv) görünür. Çıkmak için her kabukta deactivate. Etkinleştirmeden de çalışabilirsin: .venv/bin/python betik.py (Windows'ta .venv\Scripts\python.exe betik.py) doğrudan o ortamın Python'ını kullanır; zamanlanmış görevlerde ve CI'da en güvenli yol budur.

# Windows PowerShell: "running scripts is disabled on this system" hatası
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
.venv\Scripts\Activate.ps1
where.exe python             # ilk satır ...\.venv\Scripts\python.exe olmalı

# Debian/Ubuntu: "ensurepip is not available" hatası
sudo apt install python3-venv          # (ya da python3.12-venv)
python3 -m venv .venv && source .venv/bin/activate
which python                 # .../proje/.venv/bin/python olmalı

# Ortamı sıfırdan kurmak (bozulduysa): klasörü sil, yeniden oluştur
rm -rf .venv                 # Windows: Remove-Item -Recurse -Force .venv
python3 -m venv .venv --upgrade-deps   # pip'i de güncel kurar

Hangi ortamda olduğunu kodla da anlayabilirsin: sanal ortamda sys.prefix ortam klasörünü, sys.base_prefix ise ana kurulumu gösterir.

import sys, sysconfig, platform
from pathlib import Path

print("Python:", platform.python_version(), "| sistem:", platform.system())
print("Çalışan yorumlayıcı:", sys.executable)
print("Sanal ortamda mı?", sys.prefix != sys.base_prefix)
print("Paketler buraya kurulur:", sysconfig.get_paths()["purelib"])

isaret = Path(sysconfig.get_paths()["stdlib"]) / "EXTERNALLY-MANAGED"
print("PEP 668 korumalı sistem Python\'ı mı?", isaret.exists())

2. pip: günlük komutların tamamı

python -m pip install requests                 # en son sürüm
python -m pip install "pandas>=2.2,<3"         # aralık (tırnak şart: < ve > kabuk yönlendirmesidir)
python -m pip install pandas==2.2.3            # tam sürüm
python -m pip install -U pandas                # güncelle (--upgrade)
python -m pip install -U pip                   # pip'in kendisini güncelle
python -m pip install -r requirements.txt      # dosyadan
python -m pip install -e .                     # projeyi düzenlenebilir (editable) kur
python -m pip install "httpx[http2]"           # ekstralarla (extras)
python -m pip install --dry-run -r requirements.txt   # ne kurulacağını göster, kurma

python -m pip uninstall -y requests            # kaldır (bağımlılıkları KALDIRMAZ)
python -m pip show pandas                      # sürüm, konum, Requires, Required-by
python -m pip list                             # kurulu paketler
python -m pip list --outdated                  # güncellenebilenler
python -m pip freeze > requirements.txt        # tam sürümlerle döküm
python -m pip check                            # kırık bağımlılık var mı?
python -m pip download -d paketler -r requirements.txt   # internetsiz kurulum için indir
python -m pip install --no-index --find-links paketler -r requirements.txt
python -m pip cache purge                      # bozuk önbelleği temizle
python -m pip config list                      # aktif pip ayarları

3. requirements ve constraints

requirements.txt "bunları kur" der. constraints.txt (-c) ise "kurarsan şu sürümü kullan" der ama kendisi hiçbir şey kurmaz. Şirket genelinde onaylı sürümleri tek dosyada tutmak için idealdir: her proje kendi requirements'ını yazar, sürümler ortak constraints'ten gelir.

# requirements.txt
pandas>=2.2
requests
-c constraints.txt        # dosya içinden de bağlanabilir

# constraints.txt  (şirket onaylı sürümler)
pandas==2.2.3
numpy==2.1.3
requests==2.32.3
django==5.1.4             # kimse istemezse kurulmaz

python -m pip install -r requirements.txt -c constraints.txt

Kurulu sürümleri Python içinden okumak (ör. bir betiğin başında "doğru sürüm mü?" kontrolü) için importlib.metadata kullanılır:

from importlib.metadata import version, PackageNotFoundError

for paket in ("pip", "pandas", "olmayan-paket-xyz"):
    try:
        print(f"{paket:20} {version(paket)}")
    except PackageNotFoundError:
        print(f"{paket:20} KURULU DEĞİL -> python -m pip install {paket}")

4. pip-tools: elle yazılan liste + otomatik kilit

python -m pip install pip-tools
# requirements.in : yalnız doğrudan ihtiyaçlar
#   pandas>=2.2
#   httpx
pip-compile requirements.in              # -> requirements.txt (tüm alt bağımlılıklar sabit, yorumlu)
pip-compile --upgrade-package httpx      # yalnız birini güncelle
pip-compile --generate-hashes            # özet doğrulamalı kilit (güvenlik)
pip-sync requirements.txt                # ortamı dosyayla BİREBİR eşitle (fazlaları kaldırır)

5. uv: hızlı, hepsi bir arada

uv, Rust ile yazılmış, pip'ten kat kat hızlı bir araçtır; Python sürümü kurmayı, sanal ortamı, kilit dosyasını ve araç kurulumunu tek komutta toplar.

# Kurulum: macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv python install 3.12            # Python'ı uv kursun
uv venv                           # .venv oluşturur (--python 3.12 ile sürüm seç)
uv pip install -r requirements.txt     # pip ile aynı arayüz, çok daha hızlı
uv pip compile requirements.in -o requirements.txt   # pip-tools karşılığı
uv pip sync requirements.txt

# Proje modu (pyproject.toml + uv.lock)
uv init anadolu-rapor && cd anadolu-rapor
uv add pandas "httpx>=0.27"       # pyproject'e yazar, kilitler, kurar
uv add --dev pytest ruff          # geliştirme bağımlılığı
uv remove httpx
uv lock                           # uv.lock'u güncelle (kurmadan)
uv lock --upgrade-package pandas
uv sync                           # ortamı kilide göre kur (CI'da: uv sync --locked)
uv run python rapor.py            # ortamı etkinleştirmeden çalıştır
uv tool install ruff              # pipx karşılığı

6. poetry

pipx install poetry
poetry new ilgaz-bank   # ya da mevcut projede: poetry init
poetry add pandas@^2.2    # ^2.2 = >=2.2,<3.0
poetry add --group dev pytest
poetry install            # poetry.lock'tan kur
poetry lock               # kilidi yenile
poetry run pytest
poetry env info --path    # ortamın yeri
poetry export -f requirements.txt -o requirements.txt   # (poetry-plugin-export gerekir)

7. conda (Anaconda / Miniconda / Miniforge)

Conda yalnız Python paketlerini değil, C/C++ kütüphaneleri ve hatta Python'ın kendisini yönetir; GDAL, CUDA gibi derlenmiş bağımlılıklarda ve veri bilimi ekiplerinde yaygındır. Kurumsal lisans koşulları nedeniyle birçok şirket varsayılan kanal yerine conda-forge ve Miniforge kullanır.

conda create -n anadolu python=3.12 pandas -c conda-forge
conda activate anadolu            # çıkış: conda deactivate
conda install -c conda-forge scikit-learn
conda env export --from-history > environment.yml   # yalnız senin istediklerin
conda env create -f environment.yml
conda env list
conda remove -n anadolu --all

# environment.yml
name: anadolu
channels: [conda-forge]
dependencies:
  - python=3.12
  - pandas>=2.2
  - pip
  - pip:
      - rich==13.9.4       # conda'da olmayanlar en sonda pip ile

8. pipx: komut satırı araçları için

python -m pip install --user pipx   # Ubuntu: sudo apt install pipx | macOS: brew install pipx
pipx ensurepath                      # ~/.local/bin'i PATH'e ekler; terminali yeniden aç
pipx install ruff                    # her araç kendi izole ortamında
pipx run cowsay "merhaba"            # kurmadan bir kez çalıştır
pipx upgrade-all
pipx list

9. Sık hatalar: PEP 668, SSL, proxy, sürüm çakışması

PEP 668 – error: externally-managed-environment. Ubuntu 23.04+, Debian 12+, Fedora ve Homebrew Python'ı sistem paket yöneticisine aittir; pip ile global kurulum engellenir. Çözüm her zaman bir sanal ortam (proje için) ya da pipx (araç için) kullanmaktır. --break-system-packages bayrağı adının söylediğini yapar: işletim sistemi araçlarını bozabilir.

SSL – CERTIFICATE_VERIFY_FAILED. Kurumsal ağlarda güvenlik cihazı trafiği kendi sertifikasıyla yeniden imzalar. Doğru çözüm şirketin kök sertifikasını tanıtmaktır; doğrulamayı kapatmak değil.

python -m pip install --upgrade pip              # pip 24.2+ sistem sertifika deposunu (truststore) kullanır
python -m pip config set global.cert C:\sertifikalar\sirket-kok.pem
# ya da ortam değişkeniyle (PowerShell: $env:PIP_CERT = "...")
export PIP_CERT=/etc/ssl/certs/sirket-kok.pem
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/sirket-kok.pem   # requests/httpx için
# macOS python.org kurulumunda: "Install Certificates.command" dosyasını çalıştır

# Proxy: 407 Proxy Authentication Required / ProxyError
export HTTPS_PROXY=http://kullanici:parola@proxy.sirket.local:8080
python -m pip install --proxy http://proxy.sirket.local:8080 pandas
# Şirket içi ayna (Artifactory/Nexus)
python -m pip config set global.index-url https://nexus.sirket.local/repository/pypi/simple

Uzun bir ResolutionImpossible çıktısında asıl bilgi "X depends on Y" satırlarındadır. Onları ayıklayıp aynı paketi kimin hangi aralıkla istediğini yan yana görmek çakışmayı hemen ortaya çıkarır:

import re
from collections import defaultdict

hata = """ERROR: Cannot install anadolu-rapor and eski-grafik because these package versions have conflicting dependencies.
The conflict is caused by:
    anadolu-rapor 1.4.0 depends on numpy>=2.0
    eski-grafik 0.9.1 depends on numpy<1.25
    anadolu-rapor 1.4.0 depends on pandas>=2.2
ERROR: ResolutionImpossible"""

isteyenler = defaultdict(list)
for kim, surum, paket, kosul in re.findall(r"([\w.-]+) ([\d.]+) depends on ([\w.-]+)(\S*)", hata):
    isteyenler[paket].append(f"{kim} {surum} -> {kosul or 'herhangi'}")
for paket, liste in isteyenler.items():
    isaret = "ÇAKIŞMA ADAYI" if len(liste) > 1 else "tamam"
    print(f"{paket}: {isaret}")
    for satir in liste:
        print("   ", satir)