Python venv ile Sanal Ortam ve pip Kullanımı

Sanal ortam hangi sorunu çözer?

Python uygulamaları çoğu zaman standart kütüphanede olmayan paketlere ihtiyaç duyar ve bazen bu paketlerin belirli bir sürümüne bağlıdır. Resmî tutorial şu örneği verir: A uygulaması bir paketin 1.0 sürümünü, B uygulaması 2.0 sürümünü istiyorsa tek bir Python kurulumu ikisini birden memnun edemez; hangi sürümü kurarsanız kurun uygulamalardan biri çalışmaz. Çözüm her uygulamaya kendi sanal ortamını vermektir. B'nin ortamında paketi 3.0 sürümüne yükseltmek A'yı etkilemez.

venv belgelerine göre bir sanal ortam şu özellikleri taşır:

• Bir projenin ihtiyaç duyduğu yorumlayıcıyı, kütüphaneleri ve çalıştırılabilir dosyaları içerir; varsayılan olarak diğer ortamlardan ve işletim sistemindeki paketlerden yalıtılmıştır.
• Bir klasörde durur; geleneksel adı proje klasöründe .venv ya da venv olur.
• Git gibi sürüm kontrol sistemlerine eklenmez.
• Kullanılıp atılabilir kabul edilir: silip baştan oluşturmak kolay olmalıdır ve içine proje kodu konmaz.
• Taşınabilir ya da kopyalanabilir kabul edilmez; başka bir konumda gerekiyorsa orada yeniden oluşturulur.

Her sanal ortam, oluşturulduğu Python kurulumunun üzerine kurulur; belgeler buna ortamın base Python'u der. Ortamda hangi Python sürümü olacağını, komutu hangi yorumlayıcıyla çalıştırdığınız belirler: python3.15 -m venv .venv 3.15 tabanlı bir ortam üretir.

Sanal ortam oluşturmak

Proje klasörüne geçip venv modülünü betik gibi çalıştırın. Klasör adı olarak .venv tutorial'ın önerdiği yaygın bir seçimdir: kabukta gizli görünür, ne işe yaradığını adından anlatır ve bazı araçların kullandığı .env ortam değişkeni dosyalarıyla karışmaz (.env dosyası nedir).

# macOS / Linux
python3 -m venv .venv

# Windows (python komutu PATH üzerindeyse)
python -m venv .venv

# Windows, Python install manager ile belirli sürüm
py -V:3.15 -m venv .venv

Windows'taki py komutu birden çok Python sürümü kuruluysa belirli bir sürümü seçmenizi sağlar; resmî sürümlerde V: kısmı yazılmadan py -3.15 biçimi de kabul edilir. Kurulum ve py komutunun ayrıntıları için Python kurulumu yazısına bakabilirsiniz.

Komut hedef klasörü (gerekirse üst klasörleriyle birlikte) oluşturur. Windows'ta oluşan yapıyı Python 3.12.7 ile şöyle gördük:

$ python -m venv .venv
$ ls .venv
Include  Lib  Scripts  pyvenv.cfg
$ ls .venv/Scripts
Activate.ps1  activate  activate.bat  deactivate.bat  pip.exe  pip3.12.exe  pip3.exe  python.exe  pythonw.exe
$ ls .venv/Lib/site-packages
pip  pip-24.2.dist-info

POSIX sistemlerde (macOS, Linux) Scripts yerine bin, Lib\site-packages yerine lib/pythonX.Y/site-packages klasörü oluşur; bin klasörüne de platforma ve seçeneklere göre yorumlayıcının bir kopyası ya da sembolik bağlantısı konur. Kurduğunuz her paket site-packages klasörüne gider. Python 3.15 sürüm notlarına göre POSIX platformlarda sys.platlibdir değeri lib olmayan sistemlerde artık lib64 -> lib sembolik bağlantısı kullanılmıyor; gerekirse ayrı bir platlib klasörü oluşturuluyor.

Klasörün kökündeki pyvenv.cfg dosyası ortamın kimlik kartıdır. home anahtarı ortamı oluşturan Python kurulumunu gösterir, include-system-site-packages sistem paketlerine erişim olup olmadığını belirtir (son satırdaki uzun klasör yolunu kısalttık):

home = C:\Program Files\Python312
include-system-site-packages = false
version = 3.12.7
executable = C:\Program Files\Python312\python.exe
command = C:\Program Files\Python312\python.exe -m venv C:\...\vproje\.venv

Ortamı etkinleştirmek ve kapatmak

Etkinleştirme betiği, ortamın bin ya da Scripts klasörünü PATH değişkeninin başına ekler. Böylece python ve pip komutları ortamın içindeki kopyaları çalıştırır; kabuk istemi de ortamın adını gösterir. Komut, kullandığınız kabuğa göre değişir:

Etkin ortamdan çıkmak için hangi kabukta olursanız olun deactivate yazmanız yeterlidir. Etkinleştirildiğinde VIRTUAL_ENV ortam değişkeni ortamın yoluna ayarlanır; ancak belgeler etkinleştirmenin zorunlu olmadığını, bu yüzden bu değişkene bakarak sanal ortamda olup olmadığınıza karar vermemeniz gerektiğini vurgular.

Etkinleştirilmiş ortamın, PYTHONPATH değişkenine dokunmadığını da bilmekte fayda var. Bu değişken başka bir Python sürümüne ait kod klasörlerini gösteriyorsa beklenmedik içe aktarma hataları görebilirsiniz; tutorial böyle durumlarda PYTHONPATH değişkenini temizlemeyi önerir.

Etkinleştirmeden kullanmak ve ortamı tanımak

Bir ortamı kullanmak için onu etkinleştirmek şart değildir: ortamın yorumlayıcısını tam yoluyla çağırmak aynı sonucu verir. Bu yöntem cron görevlerinde, systemd servislerinde ve otomasyon betiklerinde daha güvenlidir, çünkü kabuk durumuna bağlı değildir. Ortama kurulan betiklerin ilk satırındaki shebang da ortamın yorumlayıcısının mutlak yolunu içerir.

Kodun bir sanal ortamda çalışıp çalışmadığını anlamanın belgelenmiş yolu sys.prefix ile sys.base_prefix değerlerini karşılaştırmaktır. Ortam içindeyken ilki ortam klasörünü, ikincisi base Python'u gösterir:

import sys
print(sys.prefix != sys.base_prefix)
print(sys.executable.endswith(r'.venv\Scripts\python.exe'))

$ .venv/Scripts/python.exe kontrol.py
True
True
$ python kontrol.py
False
False

pip ile paket kurmak, güncellemek, kaldırmak

pip, Python'un tercih edilen paket kurucusudur ve varsayılan olarak Python Package Index (PyPI) üzerinden paket indirir. Belgeler pip'i pip yerine python -m pip biçiminde çağırmayı gösterir; bu yazım hangi Python'un pip'ini çalıştırdığınızı belirsizlikten kurtarır. Örnek paket olarak küçük bir uyumluluk kütüphanesi olan six paketini kurduk. Çıktılar ortamdaki pip 24.2 sürümüne aittir; pip'in başka sürümlerinde satırlar biraz farklı görünebilir:

$ python -m pip install "six==1.16.0"
Collecting six==1.16.0
  Downloading six-1.16.0-py2.py3-none-any.whl.metadata (1.8 kB)
Downloading six-1.16.0-py2.py3-none-any.whl (11 kB)
Installing collected packages: six
Successfully installed six-1.16.0

Temel komutlar ve ne işe yaradıkları:

Bir paket zaten kuruluysa aynı install komutu hiçbir şey yapmaz; yükseltmeyi --upgrade ile açıkça istemeniz gerekir. > ve < gibi karşılaştırma işaretleri kabuk tarafından yönlendirme sanılabileceği için belgeler paket adı ve sürümü çift tırnak içine almayı söyler. Yeni oluşturulmuş bir ortamda pip list yalnızca pip'in kendisini gösterir; 3.12 ile setuptools artık ortama varsayılan olarak kurulmuyor.

requirements.txt ile ortamı yeniden üretmek

pip freeze çıktısını requirements.txt adlı bir dosyaya yazmak yaygın bir alışkanlıktır. Bu dosya sürüm kontrolüne eklenir, ortamın kendisi eklenmez. Başka bir makinede ya da sunucuda boş bir ortam oluşturup dosyadaki paketleri aynı sürümlerle kurarsınız:

$ python -m pip freeze > requirements.txt
$ cat requirements.txt
six==1.16.0

$ python -m pip uninstall -y six
Found existing installation: six 1.16.0
Uninstalling six-1.16.0:
  Successfully uninstalled six-1.16.0

$ python -m pip install -r requirements.txt
Collecting six==1.16.0 (from -r requirements.txt (line 1))
  Using cached six-1.16.0-py2.py3-none-any.whl.metadata (1.8 kB)
Using cached six-1.16.0-py2.py3-none-any.whl (11 kB)
Installing collected packages: six
Successfully installed six-1.16.0

Dosya her satırda bir paket ve == ile sabitlenmiş sürüm içerir. Sabit sürüm, uygulamanın her kurulumda aynı kütüphanelerle çalışmasını sağlar; güncellemeyi bilinçli olarak yapıp dosyayı yeniden üretirsiniz. Bu dosya Dockerfile yazarken de bağımlılık katmanını oluşturmanın standart yoludur; Django ya da FastAPI uygulamalarını sunucuya kurarken de aynı akış kullanılır.

venv seçenekleri

python -m venv -h tüm seçenekleri listeler. Belgelerde tanımlanan seçenekler şunlardır:

--prompt magaza ile oluşturduğumuz bir ortamda pyvenv.cfg dosyasına prompt = 'magaza' satırı eklendiğini gördük. Belgeler Windows'ta sembolik bağlantıların desteklendiğini ama önerilmediğini de not eder: Dosya Gezgini'nde python.exe üzerine çift tıklandığında bağlantı hemen çözülür ve sanal ortam yok sayılır. 3.12.7 sürümünün yardım ekranında --without-scm-ignore-files seçeneği yoktu; bu, seçeneğin 3.13 ile geldiğini doğruluyor.

Baştan sona örnek: projeyi kurmak ve sunucuya taşımak

Buraya kadar anlatılanları tek bir akışta birleştirelim. Yerel bilgisayarınızda yeni bir proje başlatıyor, sonra aynı ortamı bir Linux sunucusunda yeniden kuruyorsunuz:

• 1. Ortamı oluşturun: proje klasöründe python -m venv .venv çalıştırın. Python 3.13 ve sonrasında ortam klasörü kendi .gitignore dosyasıyla gelir.
• 2. Etkinleştirin: Windows PowerShell'de .venv\Scripts\Activate.ps1, macOS ve Linux'ta source .venv/bin/activate. İstemde (.venv) önekini görmelisiniz.
• 3. Paketleri kurun: python -m pip install paket ile ihtiyaç duyduğunuz paketleri ekleyin ve uygulamanızı geliştirin.
• 4. Listeyi kaydedin: python -m pip freeze > requirements.txt çalıştırıp dosyayı depoya ekleyin; .venv klasörünü eklemeyin.
• 5. Sunucuda yeniden kurun: depoyu çektikten sonra python3 -m venv .venv ile yeni bir ortam oluşturun ve .venv/bin/python -m pip install -r requirements.txt ile paketleri kurun. Yerel ortamı sunucuya kopyalamayın; yorumlayıcı yolları ve işletim sistemi farklıdır.
• 6. Servisi ortamın yorumlayıcısıyla başlatın: systemd birimi, cron satırı ya da süreç yöneticisi .venv/bin/python uygulama.py yolunu kullanırsa etkinleştirme adımına gerek kalmaz.

Bu akışta ortam her makinede yeniden üretilebilir bir yapı olarak kalır; tek kaynak requirements.txt dosyasıdır. Bir paketi güncellediğinizde dosyayı yeniden üretip depoya işlemek, sunucudaki kurulumun yerel ortamınızla aynı sürümleri kullanmasını sağlar.

Sık yapılan hatalar

• Ortamı etkinleştirmeden pip çalıştırmak: paket sistem Python'una ya da kullanıcı klasörüne gider. python -m pip kullanmak ve komuttan önce hangi python komutunun çalıştığını kontrol etmek bu karışıklığı azaltır.
• Ortam klasörünü taşımak ya da kopyalamak: betiklerdeki shebang satırları mutlak yol içerdiği için taşınan ortam bozulur. Belgeler yeni konumda yeniden oluşturup eskisini silmeyi söyler.
• Ortamı Git deposuna eklemek: yüzlerce dosya depoya girer ve başka işletim sisteminde çalışmaz. Depoya yalnızca requirements.txt girer.
• Linux'ta sistem Python'una pip ile paket kurmak: kurulum belgeleri bunun root yetkisi gerektirdiğini ve dağıtımın paket yöneticisiyle çakışabileceğini belirtir; sanal ortam ya da kullanıcı kurulumu tercih edin.
• Proje kodunu .venv içine koymak: ortam silinip yeniden kurulabilir olmalıdır; kod proje klasöründe durur.
• pip yok hatası: pip kurulmamışsa belgeler python -m ensurepip --default-pip komutunu önerir.

Sık Sorulan Sorular

venv ile virtualenv arasındaki fark nedir?

venv Python 3.3 ile standart kütüphaneye giren ve 3.5 sürümünden beri sanal ortam oluşturmak için önerilen araçtır. virtualenv ise kurulum belgelerinde üçüncü taraf bir alternatif ve venv'in öncülü olarak anılır. Standart kütüphaneyle yetinmek istiyorsanız venv yeterlidir.

Her projede ayrı ortam mı oluşturmalıyım?

Evet, önerilen yaklaşım budur. Ortamlar hafiftir ve silinip yeniden kurulabilir; her projenin kendi .venv klasörü ve requirements.txt dosyası olması sürüm çakışmalarını önler.

Python sürümünü yükseltince ortama ne olur?

Python yerinde güncellendiyse python -m venv --upgrade .venv ortamı yeni sürüme uyarlar. Farklı bir ana sürüme geçiyorsanız (örneğin 3.14'ten 3.15'e) en temiz yol ortamı silip yeni yorumlayıcıyla yeniden oluşturmak ve requirements.txt dosyasından paketleri kurmaktır. 3.15 ile gelen değişiklikleri Python 3.15 yenilikleri yazısında topladık.

Kodum sanal ortamda mı çalışıyor, nasıl anlarım?

sys.prefix != sys.base_prefix ifadesi True ise sanal ortamdasınız. VIRTUAL_ENV değişkeni yalnızca ortam etkinleştirildiğinde ayarlandığı için güvenilir bir gösterge değildir.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Python öğrenme rehberi · Python nedir · Python kurulumu · Modül ve paket import · .gitignore rehberi · Dockerfile rehberi