Python Bağımlılık Versiyon Çakışmaları ve Kilit Dosyası Mantığı

Python bağımlılık yönetimi söz konusu olduğunda requirements.txt dosyası çoğu geliştiricinin güvendiği ilk kalkan gibi görünür, ama gerçek şu: bu dosya yalnızca projenizin doğrudan içe aktardığı üst seviye paketleri ve bunlara verdiğiniz sürüm kısıtlarını sabitler. Paketlerin arkasında sessizce çalışan, sizin hiç import etmediğiniz onlarca alt kütüphanenin hangi sürümle kurulacağını garanti etmez. Yani requirements.txt bir "kısmi fotoğraf" gibidir; çerçevenin dışında kalan çok şey, kurulum anındaki koşullara göre değişebilir.

Bu eksik fotoğraf, geliştirici camiasının çok tanıdığı bir sorunu doğurur: "bende çalışıyor ama sende çalışmıyor" durumu. Aynı requirements.txt dosyasını kullanan iki farklı makinede, farklı zamanlarda yapılan kurulumlar, aradan geçen sürede yayınlanan yeni alt paket sürümleri yüzünden birbirinden az da olsa farklı bir bağımlılık ağacı oluşturabilir. Sonuç olarak kod aynıdır, ama çalışma zamanı davranışı, hata mesajları hatta bazen içe aktarma hataları farklılaşabilir. İşte tam bu noktada "deterministik kurulum" ihtiyacı doğar: kurulumun her seferinde, her makinede, tıpkısının aynısı bir bağımlılık ağacı üretmesi gerekir. Bu ihtiyacın nasıl karşılandığını, transitive dependency kavramından başlayarak sonraki bölümlerde adım adım açacağız.

Requirements.txt Neyi Sabitler, Neyi Sabitlemez?

requirements.txt dosyasına yazdığınız her satır, projenizin doğrudan kullandığı bir pakete ve genellikle o paketin sürümüne işaret eder. Örneğin bir web uygulamasında Flask==3.0.0 yazmak, yalnızca Flask'ın kendisini sabitler; Flask'ın arkasında çalışan Werkzeug, Jinja2 veya Click gibi kütüphanelerin hangi sürümle geleceği konusunda dosyada açık bir bilgi yoktur. Bu paketler otomatik olarak kurulur, fakat hangi sürümle kurulacakları kurulum anındaki paket havuzunun durumuna bağlıdır.

Bu durum, projenin görünen bağımlılıkları ile gerçek bağımlılık ağacı arasında bir boşluk yaratır. requirements.txt'yi okuyan biri, projenin yalnızca birkaç paket kullandığını düşünebilir; oysa kurulum tamamlandığında ortamda onlarca alt paket yer alır. Bu paketlerin sürümleri zamanla değiştiği için, aynı dosyayla yapılan iki farklı kurulum, farklı tarihlerde çalıştırıldığında birbirinden az da olsa sapabilir.

Sonuç olarak requirements.txt bir başlangıç noktasıdır, kesin bir garanti belgesi değildir. Projenin gerçekten tekrarlanabilir olması için üst seviye paketlerin ötesine geçip tüm bağımlılık ağacının sabitlenmesi gerekir; bu da kilit dosyası mantığının neden ortaya çıktığını açıklayan temel motivasyondur.

Bağımlılığın Bağımlılığı: Transitive Dependency Nedir?

Bir Python paketi kurulduğunda, genellikle tek başına gelmez; kendi işlevini yerine getirebilmek için ihtiyaç duyduğu başka paketleri de beraberinde getirir. Buna transitive dependency (dolaylı/geçişli bağımlılık) denir. Somut bir örnekle düşünelim: A adlı bir paket, B paketine "1.2 ve üzeri, 2.0'dan küçük" şeklinde bir sürüm aralığıyla ihtiyaç duysun. B paketi de kendi içinde C paketine "3.0 ve üzeri" şartıyla bağlı olsun. Siz projenizde yalnızca A'yı kurduğunuzda, pip otomatik olarak B'yi ve B'nin ihtiyaç duyduğu C'yi de indirip kurar. Siz C'nin adını hiç görmemiş, hiç import etmemiş olabilirsiniz; yine de projeniz ona bağımlıdır.

Asıl karmaşa, birden fazla üst paketin aynı alt paketi farklı beklentilerle istemesiyle başlar. Diyelim ki projenizde hem A hem de D paketini kullanıyorsunuz. A paketi C'nin 3.x sürümünü isterken, D paketi C'nin 4.x sürümünü zorunlu kılıyor olabilir. Bu noktada pip, her iki üst paketi de memnun edecek tek bir C sürümü bulmaya çalışır; bazen bu mümkün olur, bazen de biri diğerinin isteğiyle çelişir ve kurulum ya bir uyarı verir ya da beklenmedik bir sürümde uzlaşır. Uzlaşma her zaman sizin test ettiğiniz kombinasyonla aynı olmayabilir.

Burada asıl dikkat edilmesi gereken nokta şudur: bu katmanlı yapı gözle görünmez. requirements.txt dosyanızı açtığınızda A ve D'yi görürsünüz, ama aralarında sessizce çakışan C'yi göremezsiniz. Proje büyüdükçe bu ağaç da büyür; bazı projelerde doğrudan bağımlılık sayısı on civarındayken, gerçek kurulan paket sayısı bunun kat kat üzerine çıkabilir. Bu görünmezlik, versiyon çakışmalarının neden aniden ve açıklaması zor biçimde ortaya çıktığını anlamanın anahtarıdır.

Versiyon Çakışması Nasıl Oluşur? Adım Adım Süreç

Bir versiyon çakışmasının nasıl adım adım oluştuğunu görmek, sorunu çözmekten çok onu öngörmeyi öğretir. Süreç genellikle şu sırayla ilerler:

1. Paket kurulur: Geliştirici requirements.txt dosyasındaki üst seviye paketi kurmak için pip install komutunu çalıştırır.
2. Alt bağımlılıklar çözümlenir: pip, kurduğunuz paketin metadata'sına bakarak hangi alt paketlere ihtiyaç duyduğunu belirler ve bunları indirmeye başlar. Bu adım bir öncekine bağlıdır çünkü alt bağımlılıklar ancak üst paket tanımlandıktan sonra ortaya çıkar.
3. Farklı paketler aynı alt bağımlılığın farklı sürümünü ister: Projede birden fazla üst paket varsa, bunların ortak bir alt pakete farklı sürüm aralıklarıyla ihtiyaç duyma ihtimali artar. Bu adım, ikinci adımda ortaya çıkan bağımlılık listelerinin kesişmesiyle doğar.
4. pip en son çözümü uygular: Çakışan istekler arasında pip'in bulduğu (genellikle o an mevcut en uygun) sürüm kurulur. Bu seçim, önceki adımda beliren çakışmanın bir çözümü niteliğindedir, ama tek olası çözüm değildir.
5. Ortam değiştiğinde farklı sürüm seçilebilir: Aynı requirements.txt başka bir zamanda veya başka bir makinede çalıştırıldığında, paket havuzunda yeni sürümler yayınlanmış olabileceği için pip farklı bir çözüme ulaşabilir. Bu adım, sürecin neden tekrarlanabilir olmadığını özetler.

Bu beş adımı okuduktan sonra kendinize şunu sorun: kendi projelerinizde requirements.txt dosyanız gerçekte hangi alt paketleri getiriyor, hiç kontrol ettiniz mi? Bağımlılık ağacı okuma ve versiyon mantığı gibi konulardaki hakimiyetinizi ölçmek isterseniz ücretsiz kodlama bilgisi testi ile mevcut seviyenizi hızlıca görebilirsiniz.

requirements.txt ile pip freeze Akışı: Terminal Örneği

Bir Python projesine başlarken izlenen klasik yol genellikle aynıdır: önce izole bir çalışma alanı kurulur, sonra paketler kurulur, en sonunda o anki durum bir dosyaya dökülür. Bu akışın mantığını satır satır görmek, requirements.txt dosyasının aslında neyi kaydettiğini anlamanın en pratik yoludur.

python -m venv venv
source venv/bin/activate
pip install requests flask
pip freeze > requirements.txt
cat requirements.txt

Bu dört komut çalıştırıldığında sırasıyla şunlar olur: venv ile izole bir Python ortamı oluşturulur, activate ile terminal bu ortama geçer, pip install ile istenen üst seviye paketler indirilir ve son olarak pip freeze o ortamda o anda kurulu olan her paketi (talep edilenler ve onların getirdiği alt paketler dahil) sürüm numarasıyla birlikte listeler. Çıktı satırları genellikle paket_adi==surum_numarasi biçimindedir ve dosyaya yönlendirildiğinde ekip arkadaşlarının kuracağı ortamın referans listesi haline gelir. Burada dikkat edilmesi gereken nokta şudur: pip freeze komutu bir tarif değil, bir anlık görüntüdür. O satırı çalıştırdığınız makinede, o dakikada, o Python sürümüyle kurulu olan paketlerin fotoğrafını çeker. Aynı komut altı ay sonra farklı bir bilgisayarda, farklı bir işletim sisteminde veya farklı bir Python yorumlayıcısıyla çalıştırıldığında, üst seviye paketler aynı görünse bile alt paketlerin çözümlenme sırası ve dolayısıyla seçilen sürümler değişebilir. Bu yüzden dosya "hangi paketleri istiyorum" sorusuna değil, "bu ortamda tam olarak neler kuruluydu" sorusuna cevap verir; ikisi arasındaki fark, ilerleyen bölümlerde ele alınacak çakışma senaryolarının temelini oluşturur.

Bağımlılık yönetiminin bu ince ayrımını pratikte deneyimlemek, kod yazmayı öğrenmekten daha çok bir alışkanlık meselesidir. birebir Python dersleri kapsamında bu tür terminal akışları gerçek proje senaryoları üzerinden adım adım uygulanarak, öğrencinin sadece komutu ezberlemesi değil, arkasındaki ortam mantığını kavraması hedeflenir.

Kilit Dosyası (Lock File) Nedir ve Nasıl Çalışır?

requirements.txt bir anlık görüntü sunarken, sektörde yaygın olarak karşılaşılan kilit dosyası mekanizması bundan bir adım öteye geçer. Kilit dosyası, projenin ihtiyaç duyduğu tüm bağımlılık ağacını -yalnızca doğrudan kurduğunuz paketleri değil, onların bağımlı olduğu her alt paketi de- kesin sürüm numaralarıyla ve genellikle her paketin bütünlüğünü doğrulayan bir hash (özet) değeriyle birlikte kaydeder. Bu yaklaşım belirli bir araca özgü bir icat değil, farklı programlama dillerinin paket yönetim araçlarında da benzer biçimde karşılaşılan genel bir çözüm desenidir.

Hash doğrulamanın işlevi basittir: bir paket ilk kez kurulduğunda o paketin dosya içeriğinden matematiksel bir özet hesaplanır ve kilit dosyasına yazılır. Aynı kilit dosyası başka bir makinede kullanıldığında, indirilen paketin hash'i yeniden hesaplanır ve dosyadaki değerle karşılaştırılır. Değerler eşleşmiyorsa kurulum bilinçli olarak durur; bu da paketin içeriğinin yanlışlıkla veya kötü niyetle değiştirilmediğini garanti eder. Programlamaya yeni başlayanlar için bu konuyu video eğitim içerikleri üzerinden görsel örneklerle izlemek, kavramı soyut kalmaktan çıkarır.

Bu iki özelliğin -tam ağaç sabitleme ve hash doğrulama- birleşimi deterministik kurulum denen sonucu doğurur: aynı kilit dosyası hangi makinede, hangi tarihte, kaç kez çalıştırılırsa çalıştırılsın, bit bit aynı bağımlılık ağacı yeniden kurulur. Üst seviye bir paketin arkasında yer alan onlarca alt paketin sürümü artık o anki paket havuzunun durumuna göre değil, dosyada donmuş olan değerlere göre belirlenir. Bu da "bende çalışıyordu ama sunucuda çalışmadı" türünden sorunların temel nedenlerinden birini ortadan kaldırır, çünkü ortam farkı denklemden çıkarılmış olur.

requirements.txt vs Kilit Dosyası: Karşılaştırma Tablosu

İki yaklaşımın hangi soruna ne ölçüde çözüm sunduğunu görmek için kriterleri yan yana koymak faydalıdır. Aşağıdaki tablo, requirements.txt'nin yalnızca istek listesi işlevi gördüğü noktalarla kilit dosyasının bunu bir garantiye dönüştürdüğü noktaları karşılaştırır.

Tablodan çıkan sonuç, iki dosyanın birbirinin rakibi değil tamamlayıcısı olduğudur: requirements.txt projenin "hangi paketlere ihtiyacım var" niyetini okunabilir biçimde ifade ederken, kilit dosyası bu niyetin her ortamda aynı şekilde gerçekleşmesini sağlayan teknik garantiyi üstlenir. Bir sonraki bölümde bu farkın takım çalışmasında neden kritik hale geldiği somut bir senaryoyla ele alınacaktır.

Takım Çalışmasında Versiyon Tutarlılığının Önemi

Bir Python projesi tek bir geliştiricinin bilgisayarında yaşamaz. Aynı kod; başka bir geliştiricinin makinesinde, CI/CD hattında test aşamasında ve nihayetinde production sunucusunda da çalışmak zorundadır. Bu dört ortamın her biri, pip install komutunu farklı bir anda, farklı bir paket indeksi anlık görüntüsüyle çalıştırabilir. Sonuç olarak aynı requirements.txt dosyası, dört ortamda dört farklı bağımlılık ağacı kurabilir. Bir geliştiricide sorunsuz çalışan bir özellik, CI sunucusunda alt bir paketin yeni sürümünde değişen bir davranış yüzünden testleri kırabilir; ya da daha kötüsü, test aşamasında fark edilmeyip doğrudan production'da hataya dönüşebilir.

Bu noktada versiyon tutarlılığı, teknik bir detay olmaktan çıkıp ekip güvenini doğrudan etkileyen bir faktöre dönüşür. Bir geliştirici "bende çalışıyor" dediğinde, bunun ekip için bir anlam ifade etmesi gerekir; aksi hâlde her hata raporu önce ortam farkı mı yoksa gerçek bir kod hatası mı olduğunu ayıklamakla başlar. Bu ayıklama süreci, özellikle transitive dependency'lerdeki gizli farklardan kaynaklandığında saatler alabilir çünkü hatanın kaynağı doğrudan import edilen bir pakette değil, o paketin arka planda çektiği bir alt pakettedir.

Kilit dosyası mantığı, bağımlılık ağacının tamamını -- doğrudan ve dolaylı tüm paketleriyle -- tek ve sabit bir liste hâline getirerek bu belirsizliği ortadan kaldırır. Herkes aynı kilit dosyasından kurulum yaptığında, "hangi sürüm kuruldu" sorusu artık bir ihtimal değil, dosyada yazan kesin bir bilgi olur. Bu da hata ayıklama süresini ciddi ölçüde kısaltır: bir sorun ortaya çıktığında ekip, ortam farkını değil doğrudan kod mantığını sorgulayabilir. Bağımlılık yönetimini bu seviyede kavramak, yalnızca araç kullanmayı değil, altındaki mantığı anlamayı gerektirir; bu yüzden 1-1 özel ders kapsamında bu tür sektörel iş akışları, öğrencinin kendi projeleri üzerinden adım adım işlenir. Sonuç olarak versiyon tutarlılığı, sadece "kod çalışsın" meselesi değil, ekip içinde zaman kaybını ve karşılıklı güvensizliği önleyen temel bir disiplindir.

Örnek Senaryo: İki Geliştirici, Aynı requirements.txt, Farklı Sonuç

Somut bir senaryo üzerinden ilerleyelim. Bir ekipteki iki geliştirici, aynı depodan aynı requirements.txt dosyasını çeker. Dosyada şöyle bir satır vardır:

requests>=2.20

Adım adım ne olduğuna bakalım:

1. Geliştirici A, projeyi bir hafta önce klonlayıp pip install -r requirements.txt çalıştırır. O anda paket indeksinde bulunan requests paketinin bağımlı olduğu alt paketlerden biri, örneğin bir şifreleme kütüphanesi, belirli bir sürümdedir.
2. Geliştirici B, aynı dosyayı bugün klonlar ve aynı komutu çalıştırır. Ancak aradan geçen sürede o alt paketin yeni bir sürümü yayınlanmıştır ve requests>=2.20 koşulunu hâlâ karşıladığı için pip bu yeni sürümü kurar.
3. Yeni sürümde, önceki sürümde var olan bir davranış değişmiş ya da kaldırılmıştır. Geliştirici A'da sorunsuz çalışan bir kod parçası, Geliştirici B'nin ortamında hata fırlatır.
4. İki geliştirici de aynı dosyayı kullandığını düşündüğü için sorunu önce kendi kodunda arar; oysa fark, hiçbirinin doğrudan yazmadığı bir alt pakettedir.

Şimdi aynı senaryoyu kilit dosyası yaklaşımıyla tekrarlayalım. Bu kez ekip, requirements.txt içindeki gevşek aralıkları çözümleyip tam ve sabit bir bağımlılık listesi üreten bir kilit dosyası kullanır. Bu dosyada hem doğrudan hem dolaylı her paketin tam sürüm numarası, isteğe bağlı olarak paket bütünlüğünü doğrulayan hash değerleriyle birlikte yazılıdır. Geliştirici A ve Geliştirici B, hangi tarihte kurulum yaparlarsa yapsınlar, kilit dosyasından kurulum yaptıkları için pip indeksteki güncel sürümlere değil, dosyada donmuş sürümlere bakar. Sonuç olarak ikisi de bit bit aynı bağımlılık ağacını kurar ve hatanın kaynağı ortam farkı olmaktan çıkar.

Bu örnek, sorunun cevabını net biçimde ortaya koyar: deterministik bir kurulum için tek başına requirements.txt yeterli değildir; çözümlenmiş tam ağacı ve mümkünse hash doğrulamasını taşıyan bir kilit dosyası gereklidir. Bu mantığı yalnızca okuyarak değil, gerçek bir proje üzerinde bozup düzelterek öğrenmek isteyenler için özel Python eğitimi içeriğinde bağımlılık yönetimi de uygulamalı olarak ele alınır.

Sık Sorulan Sorular

requirements.txt dosyası alt bağımlılıkların sürümünü de sabitler mi?

Hayır, genellikle sabitlemez. Dosyada yalnızca doğrudan yazılan paketlerin sürüm aralığı belirtilir; bu paketlerin arkasında çektiği alt paketlerin (transitive dependency) sürümü, kurulum anında paket indeksinde bulunan en uygun sürüme göre belirlenir.

Kilit dosyası (lock file) ile requirements.txt arasındaki temel fark nedir?

requirements.txt genellikle esnek sürüm aralıkları tanımlar, kilit dosyası ise bu aralıkların çözümlenmiş hâlini, yani her doğrudan ve dolaylı paketin tam ve sabit sürümünü içerir. Kilit dosyası, "ne kurulacağı" sorusuna kesin bir cevap verir.

Neden aynı requirements.txt dosyasıyla iki farklı bilgisayarda farklı sonuçlar alınabilir?

Çünkü dosyadaki sürüm aralıkları farklı zamanlarda farklı alt paket sürümleriyle eşleşebilir. Kurulum anında paket indeksinde bulunan en güncel uyumlu sürüm kurulduğu için, kurulum tarihi değiştikçe kurulan alt paketler de değişebilir.

Kilit dosyasındaki hash değerleri neyi doğrular?

Hash değerleri, indirilen paket dosyasının içeriğinin kilit dosyasında kayıtlı olanla birebir aynı olduğunu doğrular. Bu sayede kurulum sırasında beklenmedik veya değiştirilmiş bir paket dosyasının sisteme girmesi engellenir.

Takım halinde çalışırken bağımlılık tutarlılığı neden önemlidir?

Çünkü ekip üyeleri, CI/CD ortamı ve production sunucusu aynı bağımlılık ağacını kurmazsa, bir ortamda çalışan kod diğerinde hata verebilir. Bu durum hata ayıklama süresini uzatır ve sorunun kaynağının kod mu yoksa ortam farkı mı olduğunu belirsizleştirir.

pip freeze komutu bir kilit dosyası oluşturur mu?

pip freeze, o anki ortamda kurulu olan paketlerin ve sürümlerinin bir dökümünü çıkarır; bu bakımdan kilit dosyasına benzer bir çıktı verir. Ancak bağımlılık ağacının hangi paketin hangi paketi getirdiğini göstermez ve genellikle hash doğrulaması içermez, dolayısıyla tam teşekküllü bir kilit dosyası mantığıyla aynı garanti seviyesini sunmaz.

Transitive dependency (bağımlılığın bağımlılığı) nedir?

Bir projeye doğrudan eklenen bir paketin, kendi çalışması için ihtiyaç duyup arka planda otomatik olarak kurduğu başka paketlere transitive dependency denir. Geliştirici bu paketleri elle yazmaz, ancak proje bu paketlere de bağımlı hâle gelir.

Bağımlılık çakışmalarının kökeninde çoğu zaman karmaşık bir hata değil, basitçe "hangi sürümün kurulduğunu" bilmemek yatar. Bu mantığı bir kez kavrayan bir geliştirici, hem kendi projelerinde hem ekip ortamında çok daha öngörülebilir bir kurulum süreci kurabilir. Python'daki temel kavramları ne kadar sağlam bildiğinizi görmek isterseniz Python bilgi testine göz atabilirsiniz.