Python'da requirements.txt kurmak için önce projenin sanal ortamını etkinleştirir, sonra dosyanın bulunduğu klasörde pip install -r requirements.txt komutunu çalıştırırsın. Windows'ta komut py -m pip install -r requirements.txt, macOS ve Linux'ta python -m pip install -r requirements.txt biçimindedir; sistemde yalnız python3 tanımlıysa python3 -m pip install -r requirements.txt yazarsın.
Komutun çalışması için dosyanın doğru yazılmış olması ve pip'in doğru ortamı kullanması gerekir. Aşağıdaki bölümler dosya biçimini, sürüm kısıtlarını ve dosyayı pip freeze ile üretmeyi anlatıyor.
requirements.txt dosyası nasıl yazılır ve sürüm kısıtları ne anlama gelir?
requirements.txt düz bir metin dosyasıdır. Her satır pip'e kurulacak bir paketi söyler. # ile başlayan satırlar yorumdur ve pip bunları yok sayar; bir paketin yanına boşluk bırakıp # yazarak satır sonuna da açıklama ekleyebilirsin. İki paketli örnek bir dosya şöyle görünür:
# Web istekleri ve renkli terminal çıktısı
requests
richBu iki satır, pip'e sürümü sana bırakmasını söyler: paketlerin kurulabilen son sürümleri yüklenir. Sonraki bölümlerde aynı dosyayı kullanacağız.
Paket adı yazımı
pip paket adlarında büyük/küçük harf ayrımı yapmaz; Requests ile requests aynı pakete işaret eder. Asıl dikkat edeceğin nokta şu: dosyaya PyPI'daki dağıtım adı yazılır, kodda ise modül adıyla import edersin ve bu iki ad her zaman aynı değildir. Örneğin görüntü işleme paketi Pillow adıyla kurulur ama import PIL ile çağrılır; HTML ayrıştırıcı beautifulsoup4 adıyla kurulur, import bs4 ile kullanılır.
Sürüm belirteçleri
Paket adının ardına bir belirteç ve sürüm ekleyerek kısıt koyabilirsin. Genel gösterim paket==sürüm biçimindedir.
- Sürümsüz yazım: pip uygun son sürümü kurar. Aynı dosya farklı tarihlerde kurulunca farklı sürümler gelebilir.
- == (tam eşleşme): yalnız belirttiğin sürüm kurulur. Herkes aynı sürümle çalışır.
- >= (alt sınır): belirttiğin sürüm ve üstü kabul edilir. Alt sınırın altında kalan sürümler kurulmaz.
- ~= (uyumlu sürüm): sürümün son bileşeni yükselebilir, bir önceki bileşen sabit kalır. Küçük güncellemelere izin verir, büyük sıçramalara izin vermez.
Hangisini seçmelisin?
Ödev ya da öğrenme projesinde sürümsüz yazım yeterince pratiktir. Başkasının aynı ortamı kurabilmesi gerekiyorsa pip freeze çıktısındaki == satırlarını kullanmak daha güvenlidir. Başkalarının kuracağı bir kütüphane geliştiriyorsan >= ile yalnız gereken alt sınırı yazmak iyi bir başlangıçtır; böylece kullanıcıların kendi paketleriyle çakışma ihtimali azalır. Güvenlik ve hata düzeltmeleri gelsin ama sürüm sıçramasıyla uyumsuzluk çıkmasın istiyorsan ~= uygundur.
pip freeze ile requirements.txt nasıl oluşturulur?
pip freeze, etkin ortamda kurulu paketleri paket==sürüm biçiminde listeler. Çıktıyı dosyaya yönlendirmek için şunu yazarsın:
python -m pip freeze > requirements.txtWindows'ta python yerine py kullanabilirsin. Komut ekrana bir şey yazmaz; çıktı doğrudan requirements.txt dosyasına gider. Dosyayı açıp içeriğine bakman iyi bir alışkanlıktır.
Freeze neden beklediğinden uzun bir dosya üretir?
Freeze yalnız senin kurduğun paketleri değil, onların çalışması için gelen dolaylı bağımlılıkları da yazar. Bir mini senaryo: boş bir sanal ortamda yalnızca requests ve rich kurdun. Freeze çıktısında iki satır beklerken daha fazla satır görebilirsin, çünkü bu paketlerin kendi ihtiyaç duyduğu paketler de sürümleriyle listelenir.
Bunun avantajı tekrarlanabilirliktir: dosyayı başka bir bilgisayarda kuran kişi, dolaylı paketler dahil aynı sürümleri alır. Dezavantajı okunurluktur. Hangi paketi sen seçtin, hangisi kendiliğinden geldi, dosyaya bakınca ayırt etmek zorlaşır.
Seçim ölçütü basit: projenin doğrudan kullandığı birkaç paketi anlatan okunaklı bir dosya istiyorsan elle yaz. Birebir aynı ortamı yeniden kurmak istiyorsan freeze çıktısını kullan. İkisini ayrı dosyalarda tutmak da mümkündür.
Yanlış ortamda freeze çalıştırma
Freeze o an etkin olan Python ortamına bakar. Sanal ortamı etkinleştirmeden çalıştırırsan sistemdeki genel kurulumun tüm paketleri dosyaya girer ve projenle ilgisiz onlarca satır oluşur. Komuttan önce terminal satırının başında ortam adının göründüğünü kontrol et; ortamın nasıl etkinleştirileceğini sonraki bölümlerde adım adım göreceksin.
Sanal ortamda requirements.txt kurulumu: adım adım
Paketleri sistem Python'una kurmak yerine her proje için ayrı bir sanal ortam kullanmak daha güvenlidir. Her projenin kendi paket seti olur, sistem Python'u karışmaz, iki proje aynı paketin farklı sürümlerini istediğinde de çakışma yaşamazsın. requirements.txt dosyası da bu ortamın içine kurulur.
- Terminalde proje klasörüne geç.
requirements.txtdosyası bu klasörde durmalı. - Ortamı oluştur:
python -m venv .venv. Windows'tapy -m venv .venvyazabilirsin. Klasör adı seçimlidir,.venvyaygın bir tercihtir. - Ortamı etkinleştir. Komut işletim sistemine ve kabuğa göre değişir; farkı bir sonraki bölümdeki tabloda görebilirsin. Etkinleşince terminal satırının başında genellikle ortam adı görünür.
- Paketleri kur:
python -m pip install -r requirements.txt. Windows'tapy -m pip install -r requirements.txtkullanılır. Sistemindepythonkomutu yoksapython3dene. - Kurulumun çalıştığını doğrula. Bunun için çalışan bir kontrol örneğini ilerleyen bir bölümde adım adım yapacağız.
Burada pip yerine python -m pip yazmanın bir nedeni var: bu biçim, pip'i o an kullandığın Python yorumlayıcısıyla çalıştırır. Böylece paketler başka bir Python'a değil, etkin ortamdaki Python'a kurulur.
Ortam oluşturma, etkinleştirme ve kurma sırası bir kez oturduktan sonra her yeni projede aynıdır. Proje düzeni, sanal ortam ve paket yönetimi gibi alışkanlıklar düzenli pratikle ve takiple yerleşir. Birebir Python dersleri bu alışkanlıkları ödevlerle ve kişiye özel müfredatla pekiştirmek isteyenler için kurgulanmıştır.
Windows ile macOS ve Linux komutları arasındaki fark
Komutların mantığı her sistemde aynıdır; değişen, Python'u çağıran komut ve etkinleştirme betiğinin yoludur. Aşağıdaki tablo bu farkları bir arada gösterir.
| İşlem | Windows | macOS ve Linux |
|---|---|---|
| Sanal ortam oluşturma | py -m venv .venv | python -m venv .venv (gerekirse python3 -m venv .venv) |
| Ortamı etkinleştirme | PowerShell: .venvScriptsActivate.ps1Komut İstemi: .venvScriptsactivate.bat | source .venv/bin/activate |
| requirements.txt kurma | py -m pip install -r requirements.txt | python -m pip install -r requirements.txt (gerekirse python3 -m pip install -r requirements.txt) |
| freeze ile dosya üretme | py -m pip freeze > requirements.txt | python -m pip freeze > requirements.txt |
| Ortamdan çıkma | deactivate | deactivate |
PowerShell'de Activate.ps1 çalıştırılırken betik çalıştırma izni nedeniyle bir engelleme mesajı görebilirsin. Bu Windows'un güvenlik ayarıyla ilgilidir, Python'dan kaynaklanmaz. Ayarı değiştirmeden önce Microsoft'un resmî PowerShell belgelerindeki yürütme ilkeleri yönergesini okuman yerinde olur. Komut İstemi kullanmak da bu engeli aşmanın pratik bir yoludur.
Kurulumu nasıl doğrularsın? Çalışan örnekle kontrol
Kurulum komutunun hatasız bitmesi iyi bir işarettir, ama paketlerin etkin ortamda kurulu olduğunu ayrıca kontrol etmek daha güvenlidir. Aşağıdaki akış önceki örnekteki iki paketli dosyayı kullanır. requirements.txt içeriği şöyledir:
requests
richSanal ortam etkinken kurulumu yap. Windows'ta py -m pip install -r requirements.txt, macOS ve Linux'ta python -m pip install -r requirements.txt (gerekirse python3) komutunu kullan. Ardından kontrol.py adlı bir dosya oluştur:
from importlib.metadata import version
import requests
import rich
for ad in ('requests', 'rich'):
print(ad, version(ad))İki import satırı paketlerin bu yorumlayıcıdan bulunabildiğini, döngü ise kurulu sürümleri gösterir. Beklenen çıktıda her paket için bir satır görürsün: paket adı ve ardından kurulu sürüm numarası. Numara, kurulumu yaptığın gün PyPI'daki güncel sürüme göre değişebilir; bu yüzden ekranındaki değer başkasınınkinden farklı olabilir.
Ek kontroller için iki komut işini görür:
python -m pip list: etkin ortamdaki tüm paketleri ve sürümlerini listeler.python -m pip show requests: tek bir paketin sürümünü, konumunu ve bağımlılıklarını gösterir.
Betik iki farklı hata verebilir. ModuleNotFoundError, paketin bu yorumlayıcıda bulunmadığını söyler; paket büyük olasılıkla başka bir ortama kurulmuştur. importlib.metadata.version ise verdiğin ad kurulu bir dağıtımla eşleşmezse PackageNotFoundError fırlatır. Bu hata, dağıtım adını yanlış yazdığına işaret edebilir. Adı pip list çıktısındaki yazımla karşılaştır.
requirements.txt kurulurken en sık görülen hatalar ve çözümleri
1. "No such file or directory: requirements.txt"
Terminal, dosyanın bulunduğu klasörde değildir. macOS ve Linux'ta pwd ile bulunduğun yeri, ls ile klasör içeriğini gör. Windows'ta aynı iş için cd ve dir kullanılır. Dosyayı listede görmüyorsan cd ile doğru klasöre geç ya da dosyanın tam yolunu ver: python -m pip install -r /yol/proje/requirements.txt.
2. Paketler kuruldu ama import çalışmıyor
Kurulum bir yorumlayıcıya, betik başka birine gitmiş olabilir. Hangi Python'u kullandığını python --version ve python -m pip --version ile karşılaştır; ikinci komut pip'in hangi ortamda çalıştığını da gösterir. Çıplak pip yerine python -m pip yazmak, pip'i o an çağırdığın yorumlayıcıya bağlar. Pip dokümantasyonu da bu biçimi önerir.
3. "'pip' is not recognized" ya da "pip: command not found"
İlk mesaj Windows'ta, ikincisi macOS ve Linux'ta görülür. Sebep genellikle pip'in PATH'te olmamasıdır. Windows'ta py -m pip, diğer sistemlerde python -m pip ya da python3 -m pip bu sorunu çoğunlukla aşar.
4. Paket bulunamadı ya da sürüm çakışması
"No matching distribution found" veya "Could not find a version that satisfies the requirement" gibi mesajlarda önce hata satırında adı geçen paketi dosyada ara. Paket adındaki yazım hatasını, == ile yazılmış bir sürümün gerçekten var olup olmadığını ve kısıtların birbirini dışlayıp dışlamadığını kontrol et. İki paket aynı bağımlılık için uyumsuz sürümler istiyorsa pip çakışmayı bildirir; kısıtlardan birini gevşetmek çoğu durumda yeterli olur.
Hata alınca sırayla şunları sor: doğru klasördeyim, doğru ortam etkin, python -m pip kullandım, dosyadaki ad ve sürümler doğru mu?
Python ve proje düzeni üzerine daha fazla uygulamalı anlatım için Berk Akademi blogundaki yazılara göz atabilirsin.
Bir projeye başlarken ortam, dosya ve doğrulama adımlarını aynı sırayla izlemek, sonraki kurulumları da çok daha öngörülebilir kılar.
