pip "externally-managed-environment" hatası: Python sanal ortam (venv) çözümü

Ubuntu 24.04 ya da Debian 12 sunucuda bir Python paketi kurmak istiyorsunuz ve pip install şu hatayı veriyor:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install python3-xyz...

Bu bir arıza değil, bilinçli bir korumadır (PEP 668). Linux dağıtımı kendi Python paketlerini apt ile yönetir. pip ile sistem Python'una paket yüklemek, sistemin kendi araçlarını bozabilir. Debian ve Ubuntu bu yüzden sistem Python'unu pip'e kapattı. Doğru çözüm: projeniz için ayrı bir sanal ortam (venv) kullanmak.

Çözüm 1: Sanal ortam (en çok önerilen)

sudo apt install -y python3-venv python3-pip
cd /srv/uygulama
python3 -m venv venv
source venv/bin/activate
pip install requests flask
deactivate

venv klasörü projenize özel bir Python ve pip içerir. source venv/bin/activate sonrası komut satırının başında (venv) görünür ve pip install yalnızca bu ortama yükler. Etkinleştirmeden de doğrudan venv/bin/python betik.py ya da venv/bin/pip install ... yazarak kullanabilirsiniz; servis tanımlarında (systemd) bu yolu verirsiniz: Gunicorn ile yayınlama.

Bu adımlar Ubuntu 24.04'te test edilmiştir: venv oluşturulur ve içine paket kurulur. Python sürümü python3 --version ile görülür (24.04'te 3.12).

Çözüm 2: Komut satırı araçları için pipx

Bir Python uygulamasını (örneğin yt-dlp, httpie) bir komut olarak kullanmak istiyorsanız:

sudo apt install -y pipx
pipx ensurepath
pipx install httpie

pipx her aracı kendi sanal ortamına kurar ve komutu kullanıma açar; kütüphane değil, araç kurmak için uygundur.

Çözüm 3: Pakete apt ile ulaşmak

Birçok popüler Python paketi dağıtımın deposunda da bulunur: sudo apt install python3-requests python3-yaml. Sistem betikleri bu paketleri kullanır. Sürüm biraz eski olabilir ama sistemle uyumludur.

Önerilmeyen: --break-system-packages

pip install --break-system-packages paket koruma uyarısını yok sayar. Bu, sistemin kendi araçlarının bağımlı olduğu paketleri değiştirebilir (örneğin apt ve bazı sistem betikleri); sonuçta güncellemeler bozulabilir. Yalnızca geçici bir kapsayıcıda ya da ne yaptığınızı çok iyi biliyorsanız kullanın.

Sık sorunlar

• ensurepip is not available / venv oluşturulamıyor: python3-venv paketi eksiktir; yukarıdaki apt install komutunu çalıştırın.
• Başka kullanıcıyla çalıştırınca paketler yok: Sanal ortam kullanıcıya özgü değil klasöre özgüdür ama dosya sahipliği önemlidir. Servisi çalıştıran kullanıcının (www-data gibi) venv klasörünü okuyabildiğinden emin olun.
• requirements.txt ile: pip install -r requirements.txt komutunu venv etkinken çalıştırın.
• Windows'ta bu hata yoktur; Windows sunucuda Python kurulumu farklıdır: Windows'ta servis yapma.

Uygulamanızı yayınlama adımları için Node.js veya Python uygulaması yayınlama makalesine bakın. Sunucu: Linux VDS.

Sık sorulanlar

Her projeye ayrı venv mi açmalıyım?

Evet; böylece bir projenin paketleri diğerini bozmaz. venv klasörlerini sürüm kontrolüne (git) eklemeyin, requirements.txt yeter.

venv'i silip yeniden oluşturabilir miyim?

Evet, venv tek bir klasördür; silmek tüm yüklenenleri kaldırır. requirements.txt varsa yeniden oluşturmak dakikalar alır.

Python sürümünü değiştirmek istiyorum.

Sistem Python'unu değiştirmeyin. Başka bir sürüm gerekiyorsa deadsnakes deposu ya da pyenv/uv gibi araçlarla ayrı bir sürüm kurup venv'i onunla oluşturun.

İlgili makaleler

• Node.js veya Python uygulamamı sunucuda nasıl yayınlarım?
• Python Flask ya da Django uygulamasını Gunicorn ve systemd ile yayınlama
• Linux sunucuyu nasıl güncellerim?

Sorununuz çözülmediyse destek talebi açın. Hangi adımı denediğinizi ve ekranda ne gördüğünüzü yazarsanız çözüm çok daha hızlı olur.