Python'da "error: externally-managed-environment" hatası, kullandığın Python'ın işletim sistemi tarafından yönetildiğini ve pip'in oraya doğrudan paket kurmasına izin verilmediğini söyler. Çözüm, projen için ayrı bir sanal ortam (venv) oluşturup paketi orada kurmaktır. Sistem Python'ını zorlamak çözüm değildir; hatayı bir arıza olarak değil, korumalı bir ortamda olduğunun bildirimi olarak oku.
Bu hata ne anlıyor ve sistem Python'ı neden korunuyor?
Hata, pip install komutunu çalıştırdığında terminalde şu biçimde görünür. pip'in kendi yazdığı satırlar şunlardır:
error: externally-managed-environment
× This environment is externally managed
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.İlk iki satırla "note" ve "hint" satırları arasında, kullandığın sistemin kendi yönlendirme metni de çıkabilir. Bu bölümün içeriği sistemden sisteme değişir, o yüzden senin ekranında farklı görünmesi normaldir.
Bazı Linux dağıtımları ve bazı Python kurulumları, kendi araçlarını çalıştırmak için bir Python yorumlayıcısı kullanır. Sen aynı yorumlayıcıya pip ile paket ekler, günceller ya da silersen, sistem araçlarının beklediği sürümler değişebilir ve o araçlar bozulabilir. Bu yüzden dağıtım, ortamında EXTERNALLY-MANAGED adlı bir işaret dosyası bırakır. pip bu dosyayı görünce kurulumu baştan reddeder.
Yani karşında bilinçli bir koruma var. Bu kuralın standardı PEP 668'dir ve hata satırındaki "hint" de seni oraya yönlendirir. Çözüm korumayı aşmak değil, kendi çalışma ortamını kurmaktır; bunu sonraki bölümlerde adım adım yapacağız.
Önce teşhis: python ve pip hangi yorumlayıcıya bağlı?
Kurulum yapmadan önce hangi Python'la çalıştığını görmek, hatanın nedenini netleştirir. Şu adımları sırayla dene:
python3 --versionvepython3 -m pip --version: İlki Python sürümünü, ikincisi pip'in hangi Python'a ait olduğunu ve dosya yolunu yazar. Bazı sistemlerdepython3yerinepythonyazman gerekir.which python3(Linux ve macOS) ya dawhere python(Windows Komut İstemi): Terminalin çalıştırdığı yorumlayıcının tam yolunu gösterir. PowerShell'de aynı iş içinwhere.exe pythonyazılır.- Sanal ortam açık mı? Önce terminal satırının başına bak:
(.venv)gibi bir ek varsa bir sanal ortamdasın. Emin olmak için aşağıdaki satırı çalıştırabilirsin.
python3 -c "import sys; print(sys.prefix != sys.base_prefix)"Bu satır, Python'ın şu an çalıştığı ortamın ana kurulumdan farklı olup olmadığını sorar. Sanal ortamdaysan True, sistem Python'ındaysan False yazdırır.
Çıktıları şöyle yorumlayabilirsin: yol /usr/bin/python3 gibi bir sistem klasörünü gösteriyor ve sonuç False ise hata beklenen bir durumdur, çünkü sistem Python'ını kullanıyorsun. Yol proje klasörünün içindeki bir .venv klasörüne gidiyorsa kendi ortamındasın demektir.
Komutu pip install yerine python3 -m pip install biçiminde yazmanı öneririm. Bilgisayarda birden fazla Python olabilir ve çıplak pip bunlardan başkasına bağlı olabilir. python3 -m pip ise paketi, o anda çağırdığın yorumlayıcıya kurar; böylece "kurdum ama import edemiyorum" karışıklığından kaçınırsın.
Terminal ve Python temellerinde kendini nerede görüyorsan oradan devam etmek istersen, ücretsiz bilgi testleri seviyeni ölçmek için kullanışlı bir başlangıç olabilir.
Güvenli çözüm: proje klasöründe venv oluştur, etkinleştir, paketi kur
Çözüm üç komuttur. Proje klasörünün içinde terminali aç ve sırayla çalıştır:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install paket_adıKomutlar tek tek şunu yapar:
python3 -m venv .venv: Proje klasöründe.venvadlı yalıtılmış bir Python ortamı oluşturur. Sistem Python'ına dokunmaz.source .venv/bin/activate: Ortamı etkinleştirir. Terminal satırının başında(.venv)görünür vepythonilepipartık bu ortamı kullanır.python -m pip install paket_adı: Paketi etkin ortamın yorumlayıcısıyla kurur. Bu kez hata çıkmaz, çünkü ortam sana aittir.
Etkinleştirmeden sonra which python (Windows'ta where python) komutu proje_klasörü/.venv/bin/python gibi proje içindeki bir yol göstermelidir. Başka bir yol görüyorsan ortam etkin değildir.
Windows'ta fark nedir?
| Adım | Linux/macOS | Windows (PowerShell/cmd) |
|---|---|---|
| Ortam oluştur | python3 -m venv .venv | py -m venv .venv |
| Etkinleştir | source .venv/bin/activate | cmd: .venvScriptsactivate PowerShell: .venvScriptsActivate.ps1 |
| Paketi kur | python -m pip install paket_adı | python -m pip install paket_adı |
| Ortamdan çık | deactivate | deactivate |
PowerShell, betik çalıştırmayı kısıtlayan bir yürütme ilkesi nedeniyle etkinleştirme sırasında uyarı verebilir. Bu durumda cmd'de aynı adımı uygulayabilir ya da python.org'daki venv dokümantasyonunda anlatılan yönlendirmeye bakabilirsin.
Bilmen gereken üç ayrıntı
- Her yeni terminalde yeniden etkinleştir. Etkinleştirme yalnızca açık olan terminal oturumu için geçerlidir.
- Ortamı proje klasöründe tut. Hangi paketin hangi projeye ait olduğu karışmaz, bir projeyi silmek ortamını da siler.
- Ortam klasörünü paylaşma, paket listesini paylaş. Ortamdayken
python -m pip freeze > requirements.txtile liste çıkar, başka bir makinedepython -m pip install -r requirements.txtile aynı paketler kurulur.
venv komutu modül bulunamadığını ya da ortamın tam oluşturulamadığını söylüyorsa bazı Linux dağıtımlarında venv desteği ayrı gelir. Sisteminin paket yöneticisiyle venv desteğini kurman gerekebilir; hata mesajı çoğunlukla hangi paketin eksik olduğunu da yazar.
Kurulumu doğrula: sys.executable, sys.prefix ve import kontrolü
Paketin doğru yere kurulduğunu tahmin etmek yerine Python'a sorabilirsin. Ortam açıkken şu kodu çalıştır (örnekte requests kurulduğunu varsayıyoruz):
import sys
print(sys.executable)
print(sys.prefix != sys.base_prefix)
import requests
print(requests.__version__)Ortam açıksa çıktı şuna benzer:
/home/kullanici/proje/.venv/bin/python
True
(kurduğun sürüm görünür)İlk satır .venv klasörünü göstermelidir. Windows'ta yol .venvScriptspython.exe ile biter. İkinci satır True verir. Ortam kapalıyken aynı kod False ve sistem yolunu gösterir; paket de orada kurulu değilse import requests satırı hata verir.
Karşılaştırmanın nedeni şudur: sys.base_prefix ortamın dayandığı asıl Python kurulumunu, sys.prefix ise o an kullanılan ortamı gösterir. Sanal ortamın içindeyken ikisi birbirinden farklıdır; dışındayken aynıdır.
ModuleNotFoundError alırsan
İki şeyi kontrol et. Önce terminalde (.venv) ifadesi görünüyor mu, yani ortam açık mı? Sonra paket, kodu çalıştırdığın yorumlayıcıyla mı kuruldu? python -m pip list komutu etkin yorumlayıcıdaki paketleri listeler; paket listede yoksa aynı terminalde python -m pip install komutunu yeniden çalıştır.
Terminal komutları ve Python temellerini sıfırdan, kendi hızında öğrenmek istersen ücretsiz Sıfırdan Temel Python video eğitimi bu adımlar için iyi bir başlangıç olabilir.
--break-system-packages ve pipx: ne zaman, ne zaman değil?
Hata mesajını arayanlar sık sık --break-system-packages bayrağına rastlar. Bu bayrak pip'e "sistem Python'ının koruma uyarısını yok say" der ve paketi yine de sistem ortamına kurar. Adındaki "break" (bozmak) sözcüğü bilerek seçilmiştir: koruma kapanır ve sorumluluk sende kalır.
Riski şudur: işletim sisteminin kendi araçlarından bazıları sistem Python'ındaki belirli paketlere ve sürümlere dayanır. Aynı paketi başka bir sürümle değiştirirsen o araçlar beklenmedik biçimde çalışmayabilir. Geri almak da her zaman kolay olmaz, çünkü neyin neyi ezdiğini takip etmek zorlaşır. Bu yüzden bayrak yalnızca son çare sayılır ve öğrenciye önerilmez. Proje için gereken paketi bir venv içine kurmak çoğu durumda aynı işi görür ve sistemine hiç dokunmaz.
pipx ne işe yarar?
pipx, Python ile yazılmış komut satırı uygulamalarını kurmak için kullanılır. Her uygulamayı kendi izole ortamına kurar, komutu ise terminalden doğrudan çalıştırabilmeni sağlar. Yani senin yerine uygulama başına bir sanal ortam yönetir. pipx'in kendisinin nasıl kurulacağı işletim sistemine ve dağıtıma göre değişir; bunun için pipx'in resmî dokümantasyonuna bakmak doğru yoldur.
pipx kütüphane kurup kodunda import etmek için değildir. Projen için bir kütüphane lazımsa yine venv kullanırsın.
| Ne yapmak istiyorsun? | Kullanacağın yol |
|---|---|
Kodunda import ile kullanacağın bir kütüphane kurmak | Proje klasöründe venv |
| Terminalden çalıştıracağın bağımsız bir Python aracı kurmak | pipx |
| Hiçbir şey denemeden sistem ortamını zorlamak | Hayır, önce yukarıdaki iki yolu dene |
Ortam kurmayı alışkanlık yap: her proje için ayrı venv
Her proje için ayrı ortam kurmanın iki somut faydası var. Birincisi bağımlılık çakışmalarını önler: bir projede bir paketin eski sürümü, diğerinde yenisi gerekebilir ve ayrı ortamlarda ikisi birbirini bozmaz. İkincisi projeyi taşınabilir kılar: kurulu paketleri python -m pip freeze > requirements.txt ile bir dosyaya yazarsan başka bir bilgisayarda aynı ortamı yeniden kurabilirsin. Venv klasörünün kendisini kopyalamana gerek kalmaz.
Yeni bir projeye başlarken şu kısa listeyi izleyebilirsin:
- Proje için yeni bir klasör oluştur ve terminalde o klasöre gir.
python3 -m venv .venvkomutuyla ortamı oluştur (Windows'ta çoğunluklapython -m venv .venv).- Ortamı etkinleştir: Linux ve macOS'ta
source .venv/bin/activate, Windows'ta.venvScriptsactivate. - Paketleri
python -m pip install paket_adibiçiminde kur. python -c "import sys; print(sys.executable)"çıktısının proje klasöründeki.venviçini gösterdiğini doğrula.- İşin bitince
deactivateyaz ve ortamdan çık.
Terminal adımlarında takılman çok normal; ortam kurulumu çoğu kişi için ilk engeldir. Bunu bir eğitmenle birlikte yapmak istersen birebir Python Özel Ders programında kişiye özel müfredat ve ödev takibiyle bu tür pratikler düzenli biçimde çalışılır. Öğrenci Portalı'ndaki Öğrenim Asistanı da hazır çözüm vermez, adım adım düşünmene yardımcı olur.
Sık Sorulan Sorular
python3 -m venv çalışırken "ensurepip is not available" ya da venv kurulu değil hatası alıyorum, ne yapmalıyım?
Bazı Linux dağıtımlarında sanal ortam desteği Python ile birlikte gelmez, ayrı bir paket olarak sunulur. Hata mesajı çoğunlukla hangi paketin kurulması gerektiğini söyler. Paketin adı dağıtıma göre değiştiği için mesajdaki öneriyi ya da dağıtımının resmî dokümantasyonunu izle, ardından venv komutunu yeniden çalıştır.
python ile python3 komutu arasındaki fark nedir, hangisini kullanmalıyım?
Hangisinin çalıştığı sisteme göre değişir. Bazı sistemlerde yalnızca python3 tanımlıdır, bazılarında ikisi de aynı yorumlayıcıyı gösterir, Windows'ta ise sık sık python ya da py kullanılır. Hangi sürümü çalıştırdığını python --version ve python3 --version ile karşılaştırarak görebilirsin. Sanal ortamı etkinleştirdikten sonra python komutu o ortamdaki yorumlayıcıya bağlanır, bu yüzden orada python yazman yeterli olur.
Sanal ortamı her terminal açışımda yeniden etkinleştirmem gerekir mi?
Evet. Etkinleştirme yalnızca açık olan terminal oturumu için geçerlidir; yeni bir terminal açtığında proje klasörüne girip etkinleştirme komutunu tekrar çalıştırırsın. Alternatif olarak ortamdaki yorumlayıcıyı doğrudan çağırabilirsin, örneğin Linux ve macOS'ta .venv/bin/python betik.py. Kod editörleri de proje ortamını seçtiğinde bunu senin yerine yapabilir.
Hata ilk bakışta engel gibi görünse de aslında seni sistem Python'ına zarar vermekten koruyor. Her proje için kendi venv'ini kurduğunda hem bu mesajı bir daha sorun etmezsin hem de temiz çalışan projelerin olur.
