externally-managed-environment Hatası Nasıl Çözülür?

Yeni bir Ubuntu 24.04 sunucusu, bir Raspberry Pi ya da Homebrew kurulu bir Mac hazırlıyorsunuz, yıllardır yaptığınız gibi pip install requests yazıyorsunuz ve pip error: externally-managed-environment hatasıyla duruyor. Aynı komut eski bilgisayarınızda hâlâ çalışıyor; hata mesajı ise sizden apt, bir sanal ortam ya da pipx kullanmanızı istiyor.

Bu yazıda hatanın neyi koruduğunu, hangi sistemlerde ortaya çıktığını ve çözümleri önerdiğimiz sırayla anlatıyoruz; korumayı kapatan seçenek en sonda. Her komutu, hatayı yeniden ürettiğimiz bir ortamda çalıştırdık. Son bölümler, proxy sunucu arkasında pip kullanımını ve yeni ortamdan bir proxy üzerinden yapılan ilk isteği ele alıyor.

"error: externally-managed-environment" ne anlama gelir?#

pip'in, bu Python kurulumunun başka bir araca ait olduğunu söyleyen bir işaret bulduğu anlamına gelir. İşareti PEP 668 tanımlar: yorumlayıcının standart kütüphane dizinindeki EXTERNALLY-MANAGED adlı bir dosya; Debian 13'te bu dizin /usr/lib/python3.13/ olur. pip bu dosyayı Ocak 2023'te çıkan 23.0 sürümünden beri okuyor. Dosya varsa ve pip bir sanal ortamın içinde çalışmıyorsa dosyadaki metni ekrana basar ve hiçbir şey kurmadan çıkar.

Hatayı Windows 11'de pip 26.2.1 ile yeniden ürettik: Debian 13'ün işaret dosyası metnini, deneme için kurduğumuz geçici bir Python 3.14.8'in standart kütüphane dizinine koyduk ve python -m pip install requests komutunu çalıştırdık. Çıktı, Debian kullanıcılarının gördüğüyle aynı:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.13/README.venv for more information.

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ır, note ve hint satırları pip'ten gelir. Girintili blok ise işaret dosyasının metnidir; bu yüzden sisteme göre değişir: Arch Linux pacman -S python-xyz, Homebrew brew install xyz önerir, ikisi de ayrıca sanal ortamı ve pipx'i gösterir.

pip buraya neden kurulum yapmıyor?#

Aksi hâlde iki paket yöneticisi, birbirinden habersiz aynı dizine yazardı. Debian, Ubuntu ya da Arch'ta işletim sisteminin bazı parçaları Python ile yazılmıştır ve sistemin paket yöneticisinin kurduğu kütüphaneleri kullanır. Bu paket yöneticisi, o programların hangi sürümlere ihtiyaç duyduğunu kaydeder; pip bu kayıtları okumaz. PEP 668 sonucu şöyle anlatır: bir pip install, işletim sisteminin getirdiği bir kütüphaneyi yükseltebilir ya da kaldırabilir, hatta Fedora'nın kendi paket yöneticisi dnf'i bozabilir.

pip'i ayrı bir dizine yönlendirmek de sorunu çözmez. Dağıtımlar yerel olarak kurulan paketleri /usr/local gibi yerlere koyar; PEP 668'in önerdiği düzende yerel kurulumlar dağıtım paketlerinden önce gelir, dolayısıyla sistemin Python programları pip oraya ne koyduysa onu kullanır. İşaret dosyası iş bölümünü netleştirir: projeler kendi ortamlarını alır, sistem Python'u da dağıtımın kurduğu gibi kalır.

pip bir kurulumu engellemeye nasıl karar verir?#

1. Sanal ortamda olup olmadığına bakar. Sanal ortamın içinde sys.prefix, sys.base_prefix değerinden farklıdır; denetim burada biter ve kurulum devam eder.
2. İşaret dosyasını arar: sysconfig.get_path("stdlib") çağrısının döndürdüğü dizine bakar.
3. Mesajı okur: dosyadaki Error anahtarını ya da dosyada varsa çevrilmiş bir Error-<dil> anahtarını alır ve ekrana basar.
4. Hem pip install hem pip uninstall komutunu engeller. --user işe yaramaz: testimizde pip install --user requests aynı hatayla durdu. pip'i sudo ile çalıştırmak da bir şey değiştirmez.
5. --break-system-packages seçeneği denetimi atlar; aşağıda anlattığımız ortam değişkeni ve yapılandırma dosyası karşılıkları da aynı işi yapar.

Hangi durumda olduğunuzu görmek için kullanmak üzere olduğunuz yorumlayıcıya sorun:

python3 -c "import os, sys, sysconfig; print('venv:', sys.prefix != sys.base_prefix); print('marker:', os.path.isfile(os.path.join(sysconfig.get_path('stdlib'), 'EXTERNALLY-MANAGED')))"

pip kurulumu yalnızca çıktı venv: False ve marker: True olduğunda engeller. Sanal ortamın içinden temel yorumlayıcının işaret dosyası görünmeye devam eder; bu yüzden bizim sanal ortamımız da marker: True yazdı, ama ilk satır venv: True idi ve pip kurulumu sorunsuz yaptı.

İşaret dosyası hangi sistemlerde var?#

Debian, Ubuntu, Raspberry Pi OS, Arch Linux ve Homebrew bu dosyayı getirir; Fedora ve resmî Docker imajları getirmez.

Debian, Python 3.11 paketini Debian 12 yayımlanmadan önce işaretledi; Ubuntu 23.04 de aynı paketle çıktı. Bu yüzden Ubuntu 24.04 LTS ve Windows'ta WSL içinde çalıştırılan Ubuntu ya da Debian sistemleri de aynı mesajı gösterir. Fedora başka bir yol seçer: işaret dosyası koymaz, sudo pip install kurulumlarını /usr/local dizinine yönlendirir.

1. çözüm: projeniz için bir sanal ortam oluşturun#

Sanal ortam (virtual environment, kısaca venv), kendi python komutu ve kendi paket klasörü olan bir dizindir; sistem yorumlayıcısına bağlıdır ama onun paketlerinden ayrıdır. pip, sanal ortamın içinde PEP 668 denetimini atlar ve oraya kurduğunuz hiçbir şey sisteme dokunamaz.

cd ~/my-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests

Testimizde son komut şu satırla bitti:

Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0

Etkinleştirme (activate), ortamın bin dizinini PATH değişkeninizin başına ekler. Python'un venv dokümantasyonu her kabuk için komutu listeler; Windows'ta komut .venv\Scripts\activate olur. Etkinleştirmeyi atlayıp ortamın yorumlayıcısını doğrudan da çağırabilirsiniz; betiklerde, cron görevlerinde ve systemd servislerinde daha güvenli olan biçim budur:

.venv/bin/python -m pip install requests
.venv/bin/python app.py

.venv klasörünü silinip yeniden kurulabilecek bir şey olarak görün. Onu Git'e eklemeyin (Python 3.13'ten beri venv klasörün içine bir .gitignore dosyası yazar), paketlerinizi python -m pip freeze > requirements.txt ile kaydedin ve başka bir yerde python -m pip install -r requirements.txt ile yeniden kurun. Sanal ortam başka bir dizine ya da bilgisayara taşınmaya veya kopyalanmaya dayanmaz; orada yeniden oluşturun.

VS Code'da Python eklentisi çalışma alanındaki .venv klasörünü bulur ve onu tercih eder. Başka bir yorumlayıcı seçerse Komut Paleti'nden (Command Palette; Ctrl+Shift+P, Mac'te Cmd+Shift+P) Python: Select Interpreter (Python: Yorumlayıcı Seç) komutunu çalıştırıp .venv içindekini seçin; yeni terminaller bundan sonra ortam etkin hâlde açılır.

Debian ve Ubuntu'da "ensurepip is not available" hatası#

Debian, venv desteğini ayrı bir pakette dağıtır; bu yüzden minimal bir sunucuda python3 -m venv .venv komutunun kendisi de hata verebilir. Debian'ın yamaladığı venv modülü şu mesajı, Python'unuzun sürüm numarasıyla basar:

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.13-venv

Paketi kurun (python3-venv, sürüme özel paketi de birlikte getirir), yarım kalan klasörü silin ve komutu yeniden çalıştırın:

sudo apt install python3-venv
rm -rf .venv
python3 -m venv .venv

2. çözüm: komut satırı araçlarını pipx ile kurun#

Kurmak istediğiniz şey bir kütüphane değil de bir programsa (kod biçimlendirici, linter ya da HTTP istemcisi gibi), hata mesajının da önerdiği pipx'i kullanın. pipx her uygulama için ayrı bir sanal ortam oluşturur ve uygulamanın komutlarını PATH üzerine koyar; böylece araçlar birbirinin bağımlılıklarını bozmaz.

sudo apt install pipx      # macOS: brew install pipx
pipx ensurepath
pipx install ruff

pipx ensurepath komutundan sonra yeni bir terminal açın. Testimizde pipx install ruff, installed package ruff 0.17.0 satırını yazdı ve ruff komutu hemen çalıştı; aracı daha sonra pipx upgrade ruff ile güncelleyip pipx uninstall ruff ile kaldırabilirsiniz. Öbür sistemlerin komutları pipx kurulum rehberinde yer alıyor.

3. çözüm: dağıtımın kendi paketini kullanın#

Sistemdeki bir betiğin ihtiyaç duyduğu kütüphane, dağıtımda zaten paket olarak bulunabilir. Debian, Ubuntu ve Raspberry Pi OS Python kütüphanelerini python3-<ad>, Arch ise python-<ad> biçiminde adlandırır:

sudo apt install python3-requests     # Debian, Ubuntu, Raspberry Pi OS
sudo pacman -S python-requests        # Arch Linux

Bu sürümler dağıtımın güvenlik güncellemelerini alır, ama çoğu zaman PyPI'daki son sürümün gerisinde kalır. Homebrew uygulamaları paketler; kütüphaneler için kendi dokümantasyonu sizi sanal ortama yönlendirir.

Bazen bir projenin ikisine birden ihtiyacı olur: Raspberry Pi'de apt ile gelen bir donanım kütüphanesine ve PyPI'dan daha yeni bir pakete. Ortamı python3 -m venv --system-site-packages .venv ile oluşturun. Sanal ortam sistemin paketlerini görür, pip ise yine yalnızca sanal ortama kurar. Testimizde requests .venv klasörüne kuruldu; sistemde zaten kurulu olan bir kütüphane ise sistem klasöründen yüklendi.

4. çözüm: ortamlar ve araçlar için uv kullanın#

uv, pip, venv ve pipx'in birçok komutunun yerini tek bir programla alan bir paket ve proje yöneticisidir. İşaret dosyasına o da uyar: işaretlediğimiz Python'a karşı uv pip install --system komutu error: The interpreter at … is externally managed hatasıyla ve ardından aynı Debian metniyle durdu. uv'nin olağan akışı bir sanal ortamla çalıştığı için hata zaten çıkmaz:

uv venv
uv pip install requests
uv tool install ruff

uv venv, bulunduğunuz klasörde .venv oluşturur; uv pip install etkinleştirme gerekmeden oraya kurar; uv tool install ise pipx install komutunun karşılığıdır. Üçü de testimizde çalıştı.

Konteynerler ve CI süreçleri#

Docker Hub'daki resmî python imajları kendi Python'larını /usr/local altına derler ve işaret dosyası içermez; bu yüzden pip install bu imajlarda eskisi gibi çalışır. Hata, Dockerfile bir debian ya da ubuntu imajından başlayıp Python'u apt ile kurduğunda ortaya çıkar. Çözüm dizüstü bilgisayardakiyle aynıdır: python3-venv paketini kurun, ortamı RUN python3 -m venv /opt/venv ile oluşturun ve ENV PATH="/opt/venv/bin:$PATH" satırını ekleyin. Bundan sonraki her RUN pip install -r requirements.txt ve konteynerin python komutu, tıpkı etkinleştirmeden sonra olduğu gibi sanal ortamı kullanır.

CI sistemleri çoğu zaman her adım için yeni bir kabuk başlatır; önceki bir adımdaki etkinleştirme bu yüzden kaybolur. Her adımda ortamın yorumlayıcısını yoluyla çağırın (.venv/bin/python -m pip install …, .venv/bin/python -m pytest).

--break-system-packages neden son çare?#

Çünkü çakışmayı çözmez, korumayı kapatır ve bunu gerçekten yapar: testimizde pip install --break-system-packages requests paketi işaretli Python'a kurdu; PIP_BREAK_SYSTEM_PACKAGES=1 ortam değişkeni ve bir pip yapılandırma dosyasının [global] bölümüne yazılan break-system-packages = true satırı da aynı sonucu verdi. Bu seçenek kurulumu güvenli hâle getirmez, yalnızca uyarıyı kaldırır; pip artık sistemin kendi araçlarının kullandığı bir kütüphaneyi yükseltebilir ya da kaldırabilir. Sonraki bir sistem güncellemesi de pip'in kurduklarının üzerine yazabilir.

EXTERNALLY-MANAGED dosyasını silmek, bilgisayardaki her kullanıcı ve her program için aynı sonucu doğurur. Bu seçeneğe gerçekten ihtiyacınız varsa onu zararın sınırlı kaldığı bir yerde kullanın: yeniden kurduğunuz bir konteynerde ya da bir sanal makinede. Kabuk profiline ya da genel pip yapılandırmasına asla yazmayın; orada sonraki her kuruluma sessizce uygulanır.

Proxy sunucu arkasında pip nasıl kullanılır?#

Proxy adresini pip'e --proxy seçeneğiyle, HTTPS_PROXY değişkeniyle ya da yapılandırma dosyasıyla verin. Şirket ve kampüs ağları web trafiğine çoğu zaman yalnızca kullanıcı adı ve şifre isteyen bir proxy sunucu üzerinden izin verir; pip de eksik kimlik bilgisini proxy sorunu olarak bildirmez. Kimlik bilgisi vermediğimizde yerel test proxy'miz her denemeye 407 durum koduyla cevap verdi; pip beş yeniden deneme satırı (dördünü aşağıda çıkardık) ve yanıltıcı bir sonuç yazdı:

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'OSError('Tunnel connection failed: 407 Proxy Authentication Required')': /simple/requests/
ERROR: Could not find a version that satisfies the requirement requests (from versions: none)
ERROR: No matching distribution found for requests

from versions: none, paketin olmadığı anlamına gelmez; pip paket dizinine hiç ulaşamamıştır. pip kullanım kılavuzu bütün seçenekleri listeler; çoğu durumu şu üçü karşılar:

# tek bir komut için
python -m pip install --proxy http://user:pass@proxy.example.com:8080 requests

# bu kabuktaki her komut için
export HTTPS_PROXY=http://user:pass@proxy.example.com:8080

# yalnızca etkin sanal ortamda kalıcı olarak
python -m pip config --site set global.proxy http://user:pass@proxy.example.com:8080

Üçü de requests paketini test proxy'miz üzerinden kurdu. --site ile pip ayarı sanal ortamın kendi yapılandırma dosyasına yazdı (pip.conf, Windows'ta pip.ini); bu seçenek olmadan pip config set, her ortamı etkileyen kullanıcı düzeyindeki dosyanıza yazar. Şifrede @, : ya da / varsa bu karakterleri yüzde kodlamasıyla (percent-encoding) yazın; kodlamayı ve öbür kimlik bilgisi hatalarını HTTP 407 Proxy Authentication Required Hatası Nasıl Çözülür? yazısında anlattık.

HTTPS trafiğini denetleyen bir proxy'nin arkasında sıradaki hata genellikle CERTIFICATE_VERIFY_FAILED olur. pip 24.2 ve sonrası işletim sisteminin sertifikalarına da güvendiği için BT ekibinin sistem deposuna kurduğu şirket kök sertifikası çoğu zaman sorunu çözer; --cert seçeneği ise pip'e bir CA paketi dosyası gösterir. Nedenleri birbirinden ayırmayı Unable to Get Local Issuer Certificate Hatası Nasıl Çözülür? yazısında anlattık.

Sanal ortamdan bir proxy üzerinden ilk istek nasıl gönderilir?#

requests sanal ortama kurulduktan sonra proxy üzerinden istek göndermek tek bir sözlük ister. Betik proxy adresini bir ortam değişkeninden okur; böylece kimlik bilgileri kodun dışında kalır:

import os
import sys

import requests

# Proxy panelinizdeki endpoint ve kimlik bilgileri
PROXY = os.environ.get("PROXY_URL", "http://user:pass@pr.proxynet.io:8000")
proxies = {"http": PROXY, "https": PROXY}

print("Python:", sys.executable)
try:
    r = requests.get("https://example.com/", proxies=proxies, timeout=15)
    print("Status:", r.status_code)
except requests.exceptions.ProxyError as err:
    print("Proxy error:", err)

Betiği .venv/bin/python first_request.py ile çalıştırın. Yerel test proxy'miz üzerinden Python: satırı .venv içindeki yorumlayıcıyı gösterdi, ikinci satır da Status: 200 oldu. Yanlış şifreyle betik, Tunnel connection failed: 407 Proxy Authentication Required ile biten bir Proxy error satırı yazdı. Sistemdeki python3 ile başlatıldığında ise o noktaya hiç gelmedi: paketler sanal ortamda olduğu için ModuleNotFoundError: No module named 'requests' hatası verdi.

Hedef sitelerin isteklerinizi nasıl gördüğünü proxy türü belirler. Residential Proxy, seçtiğiniz ülke ve şehirdeki ev bağlantıları üzerinden çıkar; her istekte yeni bir adres ya da 1-60 dakikalık sticky oturum kullanabilirsiniz. Sayfaları o konumdaki ziyaretçilerin gördüğü gibi görmeniz gerektiğinde, sitenin kullanım şartlarına ve hız sınırlarına uyarak kullanın.

Datacenter Proxy size özel IPv4 adreslerini kotasız trafikle sunar; kendi servislerinizi ve API'lerinizi farklı ülkelerden düzenli olarak denetlemek gibi işlere uyar. Veri çekmek yerine göndermek istiyorsanız json= parametresini, başlıkları ve karşılık gelen cURL komutlarını Python Requests ile POST ve JSON: cURL Karşılıkları yazısında bulabilirsiniz.

Bu hatayla nerelerde karşılaşırsınız?#

• Yeni sunucular ve VPS imajları: Debian 12 ve sonrasında ya da Ubuntu 24.04'te eski kurulum betikleri hâlâ sudo pip install çağırır.
• Raspberry Pi projeleri: sensör ve GPIO kütüphaneleri için eski rehberleri izleyen kurulumlar.
• Mac bilgisayarlar: python3 komutu Homebrew'dan geliyorsa.
• Dockerfile'lar: debian ya da ubuntu imajından başlayıp Python'u apt ile kuranlar.
• Windows'ta WSL: içinde Ubuntu ya da Debian çalışır.
• CI işleri: temel imaj daha yeni bir sürüme geçtikten sonra.

Sık yapılan hatalar#

• Etkin bir sanal ortamın içinde sudo pip install çalıştırmak. Debian'da sudo, PATH değişkenini sabit bir listeyle (secure_path) değiştirir, sistemin pip'ini bulur ve hata geri gelir. Ev dizininizdeki bir sanal ortam sudo gerektirmez.
• Paketi sanal ortama kurup betiği python3 ile çalıştırmak. Sistem yorumlayıcısı sanal ortamın paketlerini görmez ve ModuleNotFoundError verir.
• .venv klasörünü Git'e eklemek ya da başka bir bilgisayara kopyalamak. Ortamı requirements.txt dosyasından yeniden kurun.
• break-system-packages ayarını genel pip yapılandırmasına yazmak. Koruma sonraki her kurulum için kapanır.

Karar rehberi#

Sıkça sorulan sorular#

Ubuntu ya da Debian'ı yükselttikten sonra pip install neden çalışmıyor?#

Yeni sürümünüz EXTERNALLY-MANAGED işaret dosyasını getiriyor ve pip 23.0 ve sonrası bu dosyaya uyuyor. Dosyayı ilk getiren sürümler Debian 12 ve Ubuntu 23.04 olduğu için hata genellikle Debian 11'den ya da Ubuntu 22.04'ten yükseltmeden sonra çıkar.

--break-system-packages kullanmak güvenli mi?#

Korumak istediğiniz bir sistemde değil. Bu seçenek, pip'in işletim sisteminin kendi Python araçlarının kullandığı kütüphaneleri değiştirmesine ya da kaldırmasına izin verir. Yalnızca yeniden kurabileceğiniz bir konteynerde ya da sanal makinede kullanın.

pip install --user hatayı aşar mı?#

Hayır. Denetim, dosyaların gideceği kullanıcı klasörüne değil yorumlayıcıya bakar; bu yüzden --user ile yapılan kurulumlar da engellenir. Testimiz de bunu doğruladı.

EXTERNALLY-MANAGED dosyasını silebilir miyim?#

Silebilirsiniz, ama bu, genel bir --break-system-packages ayarı gibi korumayı bilgisayardaki her kullanıcı ve her program için kapatır; Python paketinin sonraki bir güncellemesi de dosyayı geri getirebilir. Sanal ortam aynı sorunu bu yan etkilerin hiçbiri olmadan çözer.

Sanal ortamı her seferinde etkinleştirmem gerekir mi?#

Hayır. Etkinleştirme yalnızca o kabuktaki PATH değişkenini değiştirir. .venv/bin/python (Windows'ta .venv\Scripts\python.exe) çağrısı ortamı doğrudan kullanır; betikler, servisler ve CI için güvenilir biçim de budur.

pip sanal ortamın içinde neden hâlâ aynı hatayı veriyor?#

Çünkü çalıştırdığınız pip, sanal ortamın pip'i değil: sudo kullanmışsınızdır, etkinleştirilmemiş yeni bir terminal açmışsınızdır ya da düzenleyicinizin terminali sistem yorumlayıcısını kullanıyordur. python -m pip --version komutunu çalıştırın; yazdığı yol .venv içini göstermelidir.

Özet#

error: externally-managed-environment, işletim sisteminin pip'e sistem Python'unun onun değiştireceği bir şey olmadığını söylemesidir. Her projeye bir sanal ortam, her komut satırı aracına pipx ile kendi ortamını verin; sistem Python'unu apt, pacman ya da Homebrew'a bırakın. --break-system-packages seçeneğini gözden çıkarabileceğiniz makinelere saklayın. Betiklerinizin sitelere başka konumlardan ulaşması gerektiğinde proxy hizmetlerimize göz atın.