Python'da sanal ortam (venv) ve paket yönetimi: pip ve requirements.txt

Python'a yeni başlayanların en sık yaşadığı sorunlardan biri, paketlerin birbirine karışmasıdır: Bir projede çalışan kod, başka bir projeye paket kurduktan sonra bozulur ya da "ModuleNotFoundError" hatası alınır. Bunun çözümü her proje için ayrı bir sanal ortam kullanmaktır.

Sanal ortam nedir?

Sanal ortam, projeye özel bir Python yorumlayıcısı ve paket klasörüdür. Bu ortama kurduğun paketler sistemdeki Python'u ve diğer projeleri etkilemez.

Oluşturmak ve etkinleştirmek

Proje klasöründe:

python -m venv .venv

Etkinleştirmek için:

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Linux / macOS
source .venv/bin/activate

Etkinleştikten sonra komut satırının başında (.venv) görürsün. PowerShell betik çalıştırmayı engelliyorsa Set-ExecutionPolicy -Scope CurrentUser RemoteSigned komutu bu kısıtlamayı yalnızca senin kullanıcın için gevşetir.

Paket kurmak ve listeyi kaydetmek

pip install requests
pip freeze > requirements.txt

Projeyi başka bir bilgisayara taşıdığında ya da bir arkadaşın kodu çalıştıracağında:

pip install -r requirements.txt

Sık yapılan hatalar

• .venv klasörünü depoya eklemek: Bu klasör büyüktür ve işletim sistemine özeldir. .gitignore dosyasına ekle, yalnızca requirements.txt paylaşılsın.
• Yanlış pip: Ortam etkin değilken pip install paketleri sistem Python'una kurar. Emin olmak için python -m pip install ... kullan.
• Editör farklı yorumlayıcı kullanıyor: VS Code'da Ctrl+Shift+P → "Python: Select Interpreter" ile .venv içindeki yorumlayıcıyı seç. Aksi halde terminalde çalışan kod editörde hata verir.
• Sürüm sabitlememek: requirements.txt içinde sürüm yoksa aylar sonra farklı sürümler kurulur. pip freeze sürümleri zaten yazar.

Daha ileri seçenekler

Projeler büyüdükçe bağımlılıkları ve sürümleri daha düzenli yöneten araçlara bakabilirsin: pip-tools, Poetry ya da hızlı bir alternatif olan uv. Başlangıç için venv + requirements.txt fazlasıyla yeterlidir.

Kendi kurulumunda takıldığın bir yer olursa hata mesajının tamamını ve kullandığın komutu bu konunun altına yazabilirsin.