Python Projesinde Aynı Ortam Nasıl Yeniden Kurulur?

Bir Python projesi aynı bilgisayarda aylar sonra açıldığında bile “dün çalışıyordu” sürprizi çıkarabiliyor. Başka bir makinede kurulum yapınca hata alınması ise çoğu zaman tek bir paketten değil; Python sürümü, dolaylı bağımlılıklar, işletim sistemi kütüphaneleri ve eksik ortam değişkenlerinin birlikte değişmesinden kaynaklanıyor.

Buradaki hedef, eski sanal ortam klasörünü kopyalamak değil. Hedef; hangi girdilerle kurulduğu belli, gerektiğinde sıfırdan silinip yeniden üretilebilen bir çalışma ortamı bırakmak.

---

Önce “aynı ortam” derken neyi kastettiğinizi yazın​

Yalnızca paket adlarını aynı tutmak yeterli değildir. Tekrar kurulabilir bir ortamın kaydında en az şu katmanlar birbirinden ayrılmalı:

• Yorumlayıcı: Python’ın ana ve alt sürümü, mümkünse tam sürüm çıktısı
• Python paketleri: Doğrudan istenenler ile onların getirdiği dolaylı bağımlılıklar
• Platform: İşletim sistemi, işlemci mimarisi ve kullanılan paket dağıtımları
• Yerel kütüphaneler: Örneğin veritabanı istemcisi, derleyici, görüntü veya kriptografi kütüphanesi
• Yapılandırma: Ortam değişkenlerinin adları, özellik bayrakları ve dış servis adresleri
• Veri ve servisler: Veritabanı şeması, kuyruk, önbellek ya da başka bir çalışma zamanı bileşeni

İki makinede requirements.txt aynı olduğu hâlde biri Python 3.11, diğeri 3.13 kullanıyorsa seçilen wheel dosyaları veya desteklenen paket sürümleri değişebilir. Aynı Python sürümünde bile Linux ve Windows için farklı dağıtım dosyaları kurulabilir.

Sanal ortamı arşiv değil, yeniden üretilebilir çıktı sayın​

Python’ın resmî venv belgesi, sanal ortamları taşınabilir bir paket olarak değil, silinip yeniden oluşturulabilen ve kaynak kontrolüne alınmayan dizinler olarak tanımlıyor. Bunun önemli bir nedeni, ortam içindeki çalıştırılabilir dosya yollarının mutlak olabilmesi.

Bu yüzden .venv klasörünü başka bilgisayara kopyalamak veya Git’e eklemek sağlam bir yedek değildir. Saklanması gereken şey ortamın kendisi değil; onu kuran bağımlılık dosyaları, Python sürüm beklentisi ve işletim sistemi gereksinimleridir.

Pratik ölçü' Alıntı:

Yeni bir klasörde, eski .venv olmadan proje ayağa kalkmıyorsa kurulum tarifi henüz tamamlanmamıştır.

Genişletmek için tıkla ...

Doğrudan ve dolaylı bağımlılıkları karıştırmayın​

Uygulama kodunda bilinçli olarak kullandığınız paket doğrudan bağımlılıktır. O paketin çalışmak için getirdiği başka paketler ise dolaylı bağımlılıktır. Projenin niyetini anlatan dosyada doğrudan bağımlılıklar okunabilir kalabilir; dağıtımda kullanılan çözülmüş listede ise dolaylı bağımlılıkların da belirli sürümlere sabitlenmesi daha öngörülebilir sonuç verir.

pip freeze yararlı bir fotoğraf çeker ama neyin doğrudan seçildiğini açıklamaz. pip’in güncel komut belgesi de bunun bir lock çözümü hesaplamadığını, yalnız kurulu paketleri requirements biçiminde raporladığını açıkça söylüyor. Geliştirme sırasında deneme amacıyla kurulan gereksiz bir paket de bu fotoğrafa girebilir.

Bu nedenle sürüm güncellemesi yapılırken “tek paket satırını değiştirdim” demek yerine, çözümün yeniden üretilmesi ve ortaya çıkan tüm dolaylı değişikliklerin diff üzerinden incelenmesi gerekir.

Requirements ile lock dosyasının iki ayrı gerçeğe dönüşmesini önleyin​

En güvenli alışkanlık, hangi dosyanın insan tarafından düzenlenen girdi olduğunu baştan belirlemektir. Örneğin doğrudan bağımlılıklar pyproject.toml veya bir girdi requirements dosyasında tutulur; seçilen araç bu girdiden çözülmüş lock çıktısını üretir. Dağıtım sistemi ayrıca requirements.txt istiyorsa o dosya da aynı girdiden veya lock kaydından üretilir.

Lock ve requirements dosyasını ayrı ayrı elle güncellemek zamanla sessiz fark oluşturur. Bunun yerine tek güncelleme komutu, ardından Git diff ve temiz ortam testi kullanılmalı. Otomasyonda dosyalar yeniden üretilip beklenmeyen diff kalırsa iş başarısız sayılabilir.

Python paketleme ekosisteminde standart pylock.toml biçimi bulunuyor. Ancak “standart var” demek, kullanılan her araç ve barındırma hizmetinin bugün bu dosyayı ürettiği veya tükettiği anlamına gelmiyor. pip’in güncel pip lock belgesi de özelliği deneysel olarak işaretliyor ve üretilen dosyanın mevcut Python sürümü ile platform için geçerli olduğunu belirtiyor. Bu nedenle önce seçilen aracın sürümünde üretme, kurma ve dışa aktarma desteği doğrulanmalı; yalnız dosya adını değiştirmek lock oluşturmaz.

Küçük ve güvenli bir temiz kurulum akışı​

Aşağıdaki POSIX akışı proje dizininde çalıştırılabilir. Mevcut ortamı ezmeden önce yeni bir dizinde veya ayrı bir dalda denenmesi daha güvenlidir:


İlk iki çıktı yorumlayıcıyı ve pip’in hangi Python’a bağlı olduğunu kayda geçirir. pip check, kurulu paketlerin uyumlu bağımlılıklara sahip olup olmadığını denetler; test paketini çalıştırmanın yerini tutmaz. Ardından projenin kendi birim, entegrasyon ve başlangıç testleri çalıştırılmalı.

Komutların sözdizimi bu yazı hazırlanırken geçici bir dizinde Python 3.12.3, pip 24.0 ve temsili tek paketli requirements dosyasıyla doğrulandı. Bu doğrulama belirli bir projenin bağımlılıklarının uyumlu olduğunu kanıtlamaz; yalnız temel akışın temiz ortamda çalıştığını gösterir.

Daha sıkı dağıtım için pip’in tekrarlanabilir kurulum rehberindeki tam sürüm sabitleme ve hash denetimi değerlendirilebilir. Hash modu kullanıldığında bütün gereksinim zincirinin uygun hash kayıtlarıyla hazırlanması gerekir. Wheel arşivi de kurulumu ağdan bağımsızlaştırabilir, fakat derlenmiş wheel’ler çoğunlukla işletim sistemi ve mimariye bağlıdır.

pip dışındaki parçaları ayrıca kaydedin​

Bir Python paketi derlenirken libpq, OpenSSL başlıkları, sistem derleyicisi veya görüntü kitaplığı isteyebilir. Bunlar pip freeze çıktısında görünmez. Container taban imajını sabitlemek, sistem paketlerini ayrı bir manifestte tutmak veya kurulum belgesinde sürümleri yazmak bu boşluğu azaltır.

Ortam değişkenlerinde ise değerleri değil, gereken anahtarları belgeleyin. .env.example dosyasında DATABASE_URL= gibi boş örnekler bulunabilir; gerçek parola, API anahtarı ve token repoya eklenmemeli. Aynı kod ve paketler, eksik bir özellik bayrağı yüzünden yine farklı davranabilir.

Kurulum tamamlandı mı, nasıl anlayacağız?​

• Beklenen Python ve pip yolları yeni .venv içini gösteriyor mu?
• Doğrudan ve dolaylı paket sürümlerindeki değişiklikler incelendi mi?
• pip check ve proje testleri temiz mi?
• İşletim sistemi kütüphaneleri ile mimari kayıtlı mı?
• Gerekli ortam değişkenlerinin adları belgeli, sırlar dışarıda mı?
• Aynı kurulum CI veya ikinci bir temiz dizinde tekrarlanabiliyor mu?

Bağımlılık dosyalarını sürüm kontrolünde güvenle yönetmek için yanlış commit’i geri alma rehberine, daha geniş bağlam için programlama dillerinin geliştirme sürecindeki yerine ve test sonuçlarını ölçülebilir bir akışa bağlamak için veri odaklı geliştirme konusuna bakabilirsiniz.

Sizde temiz kurulum en çok hangi noktada bozuluyor: Python sürümünde mi, dolaylı pakette mi, yoksa sistem kütüphanesinde mi?

---