Python ModuleNotFoundError hatası, Python’ın import sırasında aradığı modülü, çalışan yorumlayıcının erişebildiği yollar içinde bulamadığını gösterir. Çözüm yalnızca pip install komutunu tekrar çalıştırmak değildir; önce hangi Python’ın çalıştığını, paketin nereye kurulduğunu, sanal ortamı, IDE ayarlarını ve yerel dosya adlarını sırayla kontrol etmek gerekir.
“Paket kurulu görünüyor” denmesine rağmen bu hatayı alabilirsin. Bunun nedeni paketin başka bir Python ortamına kurulması veya pip ile kullanılan paket adıyla Python içindeki import adının farklı olması olabilir. Bu rehber, eğitmenimiz Berk Keskin tarafından hazırlanan, güvenli bir teşhis sırasını temel alır.
ModuleNotFoundError Ne Anlama Gelir?
Python bir dosyada import paket_adi satırını gördüğünde ilgili modülü belirli arama yollarında bulmaya çalışır. Modül bu yolların hiçbirinde bulunamazsa ModuleNotFoundError: No module named '...' hatası oluşur.
Bu hata her zaman paketin bilgisayara hiç kurulmadığı anlamına gelmez. Paket, kodu çalıştıran Python yorumlayıcısından farklı bir ortama kurulmuş olabilir. Ayrıca kurulumda kullanılan paket adı ile kodda kullanılan modül adı birebir aynı olmak zorunda değildir.
Örneğin Pillow paketi, Python kodunda PIL adıyla içe aktarılır:
from PIL import ImageBu nedenle import Pillow yazmak, paketin kurulum adını doğrudan kullanmak anlamına gelmez. Hata mesajındaki modül adını, kurulum komutunda kullandığın adla karşılaştırırken bu ayrımı dikkate almalısın. Önce paketin gerçekten gerekli olup olmadığını ve doğru import adını kullandığını kontrol etmek, rastgele paket silmekten veya yönetici yetkisiyle yeniden kurulum yapmaktan daha güvenlidir.
Beş Nedeni Tek Karar Ağacında Nasıl Ayırt Edersiniz?
Teşhisi şu sırayla ilerlet: Modül adı doğru mu? Doğruysa paket, kodu çalıştıran Python’a mı kuruldu? Ardından sanal ortam etkin mi, IDE doğru interpreter’ı mı kullanıyor? Bunların hepsi doğruysa son olarak yerel dosya veya çalışma klasörü import işlemini etkiliyor mu? sorularını incele.
Windows’ta Python yolunu ve pip’in bağlı olduğu ortamı görmek için:
py -c "import sys; print(sys.executable)"
py -m pip show paket_adimacOS/Linux’ta aynı kontrolleri şu komutlarla yapabilirsin:
python3 -c "import sys; print(sys.executable)"
python3 -m pip show paket_adiİlk komut çalışan yorumlayıcının tam yolunu, ikinci komut ise paketin kurulum konumunu gösterir. Bu kontrolleri ve temel Python kavramlarını birlikte pekiştirmek için ücretsiz Python bilgi testlerinden yararlanabilirsin.
Karar ağacını kısa biçimde şöyle uygulayabilirsin:
- Import adı yanlış mı? Kodda yazan modül adını ve paketin belgelerdeki import adını karşılaştır. İsimler farklıysa import satırını düzelt.
- Paket hiç kurulmamış mı?
pip showçıktısı boşsa veya paket bulunamıyorsa, kurulumu doğrudan çalışan Python’a bağlayarak yap. Windows’tapy -m pip install paket_adi, macOS/Linux’tapython3 -m pip install paket_adikullan. - Paket farklı yorumlayıcıya mı kurulmuş?
sys.executableilepip showiçindeki konumlar farklıysa doğru yorumlayıcı üzerinden yeniden kurulum yap. - Sanal ortam yanlış mı? Terminalde etkin ortamın adı veya yolu beklediğin ortamla uyuşmuyorsa önce doğru ortamı etkinleştir; sistem geneline kurulum yapmaya çalışma.
- Yerel dosya ya da klasör adı mı çakışıyor? Proje içinde modülle aynı adlı bir dosya, klasör veya çalışma dizini varsa adını değiştirip programı proje kökünden yeniden çalıştır.
| Belirti | Kontrol | Kanıt | Sonraki adım |
|---|---|---|---|
| Modül adı şüpheli | Import ve paket adını karşılaştır | Adların farklı olduğu görülür | Import satırını düzelt |
| Paket görünmüyor | python -m pip show veya py -m pip show |
Konum bilgisi yoktur | Doğru Python ile kur |
| Kurulum var, hata sürüyor | sys.executable ve paket konumunu karşılaştır |
Yollar farklıdır | Aynı yorumlayıcıyı kullan |
| Sanal ortam karışık | Etkin ortam yolunu kontrol et | Beklenen ortam etkin değildir | Doğru ortamı etkinleştir |
| Yol veya dosya çakışması | Proje adlarını ve çalışma klasörünü incele | Aynı adlı yerel dosya ya da yanlış kök dizin bulunur | Adı veya çalışma konumunu düzelt |
Doğru Python Yorumlayıcısını ve Kurulum Konumunu Kontrol Edin
ModuleNotFoundError hatasında ilk kontrol etmen gereken şey, paketin gerçekten kodu çalıştıran Python yorumlayıcısına kurulup kurulmadığıdır. Bilgisayarında birden fazla Python kurulumu, farklı proje klasörleri veya IDE’ye ait ayrı bir yorumlayıcı bulunabilir. Bu nedenle yalnızca pip install yazmak yerine önce Python ile pip arasındaki bağlantıyı doğrula.
Windows’ta yorumlayıcı ve pip yolunu kontrol etme
py -c "import sys; print(sys.executable)"
py -m pip --versionİlk komut, py komutunun hangi Python çalıştırılabilir dosyasını kullandığını gösterir. İkinci komut ise pip’in hangi Python kurulumu üzerinden çalıştığını ve kurulum konumunu temsilî olarak gösterir.
C:...python.exe
pip ... from C:...site-packages...macOS ve Linux’ta yorumlayıcı ve pip yolunu kontrol etme
python3 -c "import sys; print(sys.executable)"
python3 -m pip --versionBurada da amaç aynıdır: python3 ile çalışan yorumlayıcı ile python3 -m pip komutunun aynı Python kurulumuna bağlı olup olmadığını görmek.
/.../bin/python3
pip ... from /.../site-packages...python -m pip, pip’i belirli bir Python yorumlayıcısı üzerinden çalıştırır. Windows’ta bunun karşılığı çoğu durumda py -m pip, macOS ve Linux’ta ise python3 -m pip biçimindedir. Böylece sistemdeki başka bir pip komutuna yanlışlıkla paket kurma ihtimalini azaltırsın. Python öğrenirken bu ayrımı kavramak, birebir Python dersleri kapsamında üzerinde durulan temel çalışma alışkanlıklarından biridir.
Kodu çalıştıran yorumlayıcıyı Python içinden doğrulayın
Terminalde gördüğün yolun gerçekten proje tarafından kullanıldığını kontrol etmek için Python dosyana veya geçici bir Python oturumuna şu satırları yaz:
import sys
print(sys.executable)C:...python.exemacOS ve Linux’ta benzer şekilde /.../bin/python3 biçiminde bir yol görebilirsin. Bu çıktı, hatayı aldığın kodu hangi yorumlayıcının çalıştırdığını gösteren en güçlü kanıtlardan biridir.
Paketin hangi klasöre kurulduğunu inceleyin
pip show paket-adıÇıktıdaki Location satırını bul:
Name: paket-adı
Location: /.../site-packagesBu klasör, paketin kurulu olduğu yeri gösterir. Location yolu ile sys.executable çıktısı farklı Python kurulumlarına işaret ediyorsa sorun büyük olasılıkla yanlış yorumlayıcıya kurulum yapılmasıdır. Bu durumda paketi, kodu çalıştıran ortam üzerinden kurmalısın.
Sanal Ortamı ve IDE Interpreter Seçimini Düzeltin
Projeye özel bir sanal ortam oluşturmak, paketlerin sistem geneline karışmasını ve farklı projelerin birbirini etkilemesini önler. Yönetici yetkisiyle tüm bilgisayara kurulum yapmak ilk çözüm olmamalıdır; önce proje klasöründe ayrı bir ortam kullanmayı dene.
Sanal ortamı oluşturma ve etkinleştirme
python -m venv .venvWindows’ta:
.venvScriptsactivatemacOS ve Linux’ta:
source .venv/bin/activateKabuk satırında .venv benzeri bir işaret görünmesi yararlı bir ipucudur; ancak tek başına kesin kanıt değildir. Etkinleştirmeden sonra yorumlayıcıyı ve pip’i aynı ortam üzerinden kontrol et:
python -c "import sys; print(sys.executable)"
python -m pip --versionArdından paketi yine aynı yorumlayıcıyla kur ve kodu da aynı ortamdan başlat:
python -m pip install paket-adı
python dosyam.pyIDE içinde seçili interpreter, terminalde etkinleştirdiğin sanal ortamdan farklı olabilir. Editör ayarlarında görünen Python yolunu, sys.executable çıktısıyla karşılaştır. Yollar aynı değilse IDE’nin proje yorumlayıcısını .venv içindeki Python dosyasına yönlendir. Bu ayrımı tek başına çözemediğinde birebir Python özel ders desteği ile proje ortamı ve kurulum adımlarını birlikte incelemek mümkün olabilir.
Yerel Dosya Gölgelemesini ve Çalışma Klasörünü İnceleyin
Kurulum doğru göründüğü hâlde ModuleNotFoundError devam ediyorsa sorun, paket yöneticisinden çok proje klasörünüzde olabilir. Python; çalıştırılan dosyanın bulunduğu klasörü ve çalışma dizinini modül arama sürecine dâhil eder. Bu nedenle kendi dosyanıza veya klasörünüze bir modül ya da paketle aynı adı vermek, Python’un beklediğiniz paketi değil yerel dosyayı bulmasına yol açabilir.
Örneğin proje klasörünüzde random.py, json.py veya kullandığınız bir paket adıyla aynı isimde bir klasör varsa import işlemi yanlış dosyaya yönlenebilir. Yüklenen dosyanın konumunu görmek için şu güvenli kontrolü kullanabilirsiniz:
import random
print(random.__file__)Çıktı, modülün hangi dosyadan yüklendiğini gösterir. Yol proje klasörünüzdeki beklenmeyen bir random.py dosyasını gösteriyorsa dosyayı örneğin rastgele_araclar.py şeklinde yeniden adlandırın. Ardından varsa ilgili __pycache__ klasörünü temizleyip programı yeniden çalıştırın.
Dosya ve klasör adları için kısa kontrol listesi
- Dosyanıza kullandığınız paket veya modül adıyla aynı adı vermeyin.
random.py,json.pygibi genel adları yardımcı dosya adı olarak kullanmadan önce dikkatli olun.- Proje klasörünüzde aynı isimli dosya ve klasör tekrarlarını arayın.
- İsimlerde gereksiz boşluk, özel karakter ve belirsiz kısaltmalar kullanmayın.
main.pydosyasını mümkünse proje kökünden çalıştırın.- Çalışma dizininin gerçekten proje kökü olduğunu terminalde kontrol edin.
Çalışma dizinini görmek için Windows’ta cd, macOS ve Linux’ta pwd komutunu kullanabilirsiniz. Proje yapınız örneğin şu kadar basit olabilir:
ornek_proje/
├── main.py
└── yardımcı_modul.pymain.py içindeki import adlarının bu yapıdaki dosya adlarıyla uyumlu olduğundan emin olun. Dosyanın adını değiştirdiğiniz hâlde eski derlenmiş dosyalar kalıyorsa __pycache__ klasörünü silmek, Python’un eski yerel modül izlerini kullanmasını önlemeye yardımcı olabilir.
Hatalı Mini Projeyi Güvenli Sırayla Çözün
Aşağıdaki örnekte, henüz kurulmamış colorama paketini kullanan bilerek hatalı bir ornek_proje/main.py dosyası vardır:
from colorama import Fore
print(Fore.GREEN + "Program çalıştı.")Paket ilgili yorumlayıcıda kurulu değilse beklenen hata şöyledir:
ModuleNotFoundError: No module named 'colorama'Önce hangi Python yorumlayıcısının çalıştığını kaydedin. Windows’ta:
python -c "import sys; print(sys.executable)"macOS ve Linux’ta da aynı komut kullanılabilir:
python3 -c "import sys; print(sys.executable)"Bir sanal ortam kullanıyorsanız önce onu etkinleştirin. Windows PowerShell için:
..venvScriptsActivate.ps1macOS ve Linux için:
source .venv/bin/activateArdından kurulumu doğrudan çalışan Python yorumlayıcısına bağlayın. Windows’ta:
python -m pip install coloramamacOS ve Linux’ta:
python3 -m pip install coloramaKurulum konumunu doğrulamak için Windows’ta python -m pip show colorama, macOS ve Linux’ta ise python3 -m pip show colorama komutunu çalıştırın. Çıktıdaki Location yolunun, az önce sys.executable ile kontrol ettiğiniz Python ortamıyla uyumlu olması gerekir.
Sonra programı aynı ortamdan çalıştırın:
python main.pymacOS ve Linux’ta komut genellikle şöyledir:
python3 main.pyBaşarılı çalışmada terminalde Program çalıştı. mesajını görürsünüz. Paket adı ile Python içindeki import adı her zaman aynı olmayabilir. Böyle bir durumda tahmin ederek farklı adlar denemek yerine paketin kendi dokümantasyonunda belirtilen doğru import ifadesini kontrol edin.
Bu tür sorunlarda yazılım öğrenme sürecini destekleyen bilgi kaynakları da kavramları pekiştirmenize yardımcı olabilir. Temel amaç, rastgele komut denemek değil, hatanın hangi ortamda ve hangi dosyadan kaynaklandığını sırayla kanıtlamaktır.
- Yorumlayıcıyı doğrula.
- Sanal ortamı etkinleştir.
python -m pipveya macOS/Linux’tapython3 -m pipkullan.pip showileLocationkonumunu kontrol et.- Yerel dosya gölgelemesini ara.
- Programı aynı ortamdan yeniden çalıştır.
Paketi hemen silip yeniden kurmak, sistem klasörlerine zorla kurulum yapmak veya yönetici yetkisi istemek ilk seçenek olmamalıdır. Bu yaklaşımlar yanlış ortamdaki kurulumu düzeltemez; ayrıca başka projelerin çalışma düzenini bozabilir. Önce yorumlayıcı, sanal ortam, kurulum konumu ve proje klasörü arasındaki uyumu doğrulamak daha güvenlidir.
Sık Sorulan Sorular
Paket kurulu göründüğü hâlde Python neden ‘No module named’ hatası verir?
Paket başka bir Python yorumlayıcısına veya başka bir sanal ortama kurulmuş olabilir. sys.executable ile çalışan yorumlayıcıyı, python -m pip show paket_adı ile kurulum konumunu karşılaştırın.
python -m pip kullanmak neden yalnızca pip yazmaktan daha güvenlidir?
python -m pip, pip komutunu belirttiğiniz Python yorumlayıcısıyla çalıştırır. Böylece sistemdeki farklı bir Python’a bağlı pip yerine programı çalıştıran ortama kurulum yapma olasılığınız artar.
Sanal ortamın doğru Python yorumlayıcısını kullandığını nasıl anlarım?
Sanal ortam etkin durumdayken import sys; print(sys.executable) komutunu çalıştırın. Çıktıdaki yolun projenizdeki .venv veya kullandığınız sanal ortam klasörünü göstermesi beklenir.
IDE’de seçili interpreter ile terminaldeki Python farklıysa ne olur?
Terminalde kurulu olan paket IDE tarafından görülmeyebilir veya IDE’nin çalıştırdığı kod terminaldekinden farklı sonuç verebilir. IDE ayarındaki interpreter yolu ile terminaldeki sys.executable çıktısını karşılaştırın.
ModuleNotFoundError hatasında paketi silip yeniden kurmak neden ilk çözüm olmamalıdır?
Hatanın nedeni çoğu zaman bozuk kurulum değil, yanlış yorumlayıcı, etkin olmayan sanal ortam veya aynı adlı yerel dosyadır. Sorunu teşhis etmeden yeniden kurulum yapmak yalnızca aynı hatayı tekrarlayabilir.
Bu güvenli teşhis sırası, Berk Akademi adına eğitmenimiz Berk Keskin tarafından hazırlanmıştır.
