Python kurulumu ve en sık karşılaşılan hatalar: adım adım çözüm rehberi

Kısa yanıt

Python kurulumu, işletim sisteminize uygun resmi kurulum dosyasını indirip çalıştırmak, kurulum sırasında Python’u PATH’e eklemek ve ardından sürümü komut satırından doğrulamaktan oluşur. Karşılaşılan hataların çoğu yanlış kurulumdan değil, PATH tanımından, python ile python3 komutlarının karıştırılmasından ve proje başına sanal ortam kullanılmamasından kaynaklanır.

Bu rehber hem sıfırdan kurulum yapan bir geliştirici hem de ekibine ortak bir Python ortamı hazırlayan bir yönetici için yazıldı: önce işletim sistemi bazında kurulum adımları, ardından en sık görülen hata mesajları ve gerçek çözümleri.

Python nedir ve kimler için doğru bir başlangıçtır?

Python, okunabilirliği ön planda tutan genel amaçlı bir programlama dilidir. Web uygulamaları, veri analizi, otomasyon betikleri ve yapay zeka modelleri aynı dil üzerinde geliştirilebilir. Kullanım alanının bu kadar geniş olması, öğrenme eğrisini düşük tutarken ekosistemini çok geniş tutmasından gelir.

• Otomasyon: Tekrarlayan dosya, rapor ve veri işlerini betikleştirmek isteyen ekipler
• Veri ve raporlama: CSV, Excel ve veritabanı verisini işleyip özet çıkaran analistler
• Web ve API: Küçük servislerden kurumsal entegrasyon katmanlarına kadar backend geliştirenler
• Yapay zeka: Hazır modelleri kendi verisiyle çalıştırmak isteyen ürün ekipleri

Kurulumdan önce netleştirilmesi gereken tek karar, hangi Python sürümünü kullanacağınızdır. Yeni bir proje için Python 3 ailesinin güncel kararlı sürümü seçilir; python.org üzerindeki indirme sayfası hangi sürümlerin desteklendiğini listeler.

Windows’ta Python kurulumu: adım adım

Windows’ta en güvenilir yol, python.org üzerindeki resmi kurulum paketidir.

1. İndirme sayfasından Windows için sunulan kararlı sürümün kurulum dosyasını indirin.
2. Dosyayı çalıştırın ve kurulum ekranının alt kısmındaki Python’u PATH’e ekle seçeneğini mutlaka işaretleyin.
3. Varsayılan kurulumu başlatıp tamamlayın.
4. Pencereyi kapatın ve komut istemini yeniden açın; yeni bir terminal açmadan PATH değişikliği görünmez.

PATH seçeneğini atlarsanız Python kurulur ama komut satırından çağrılamaz. Windows’ta yaşanan python is not recognized hatasının neredeyse tamamının nedeni budur. Kurulum ekranındaki isteğe bağlı bileşenler yeni başlayanlar için gerekli değildir.

Yeni Python sürümlerinde Windows tarafındaki önerilen kurulum yöntemi değişebiliyor; hangi yaklaşımın geçerli olduğu sürüme göre farklılık gösterdiği için resmi Windows kurulum sayfasındaki adımları esas alın.

macOS’ta Python kurulumu

macOS’ta iki yaygın yol vardır: resmi kurulum paketi ve Homebrew. Resmi paket için python.org üzerindeki macOS kurulum dosyasını indirip çalıştırmanız yeterlidir; sonrasında python3 komutu kullanılabilir hale gelir. macOS’ta python komutu her zaman Python 3’ü göstermediği için python3 yazmak daha güvenlidir.

Homebrew kullanıyorsanız tek komut yeterlidir:

brew install python

Mac’te sistemle gelen Python yorumlayıcısı, işletim sisteminin kendi araçları için ayrılmıştır. Bu yorumlayıcıya paket kurmak yerine kendi kurduğunuz sürümü ve sanal ortamları kullanmak, hem sistem kararlılığı hem de proje tekrarlanabilirliği açısından doğru yaklaşımdır.

Linux’ta Python kurulumu

Çoğu Linux dağıtımı Python 3 ile birlikte gelir. Kurulu sürümü doğruladıktan sonra eksik parçaları dağıtımın paket yöneticisiyle tamamlayabilirsiniz.

Debian ve Ubuntu tabanlı sistemlerde:

sudo apt update
sudo apt install python3 python3-pip python3-venv

Fedora ve Red Hat tabanlı sistemlerde:

sudo dnf install python3 python3-pip

Burada sık atlanan ayrıntı, sanal ortam modülünün bazı dağıtımlarda ayrı paket olarak gelmesidir; python3-venv kurulu değilse venv komutu hata verir. Kurulumdan sonra hangi yorumlayıcının çağrıldığını which python3 ile kontrol edebilirsiniz.

Kurulumu doğrulama: python –version

Kurulumun başarılı olduğunu anlamanın tek güvenilir yolu, komut satırından sürümü sormaktır.

python --version
python3 --version
py --version

Hangisinin çalıştığı işletim sistemine ve kurulum biçimine göre değişir; üçünün birden çalışması gerekmez. Aldığınız yanıt bir Python 3 sürüm numarasıysa kurulum tamamdır.

Yorumlayıcının hangi dizinden çalıştığını görmek için:

python3 -c "import sys; print(sys.executable)"

Bu komut, paket kuracağınız Python’un tam yolunu gösterir. Sanal ortam ve paket sorunlarını ayıklarken en çok işe yarayan kontrol budur: beklediğiniz yol ile ekranda görünen yol aynı değilse paketleri yanlış yorumlayıcıya kuruyorsunuz demektir.

PATH sorunu ve python is not recognized / command not found

PATH, işletim sisteminin komutları hangi dizinlerde arayacağını söyleyen ortam değişkenidir. Python kurulduğu halde komut bulunamıyorsa sorun neredeyse her zaman PATH tanımındadır.

• Windows: python is not recognized as an internal or external command mesajı, kurulumda PATH seçeneğinin işaretlenmediğini gösterir. Kurulumu kaldırıp yeniden kurmak ve bu seçeneği işaretlemek en hızlı çözümdür.
• macOS ve Linux: command not found mesajı genelde python yerine python3 yazmayı gerektirir.
• Homebrew: Kabuk yapılandırmanızın Homebrew dizinini PATH’e eklediğinden emin olun; aksi halde paket kurulu olsa da komut bulunamaz.

Yorumlayıcıyı tam yoluyla çağırmak geçici bir çözümdür; kalıcı çözüm PATH tanımını düzeltmektir. Aksi halde her terminal oturumunda aynı hatayla karşılaşırsınız.

Sürüm yönetimi ve py / python3 farkı

Aynı bilgisayarda birden fazla Python sürümü bulunması normaldir ve çoğu proje bunu gerektirir.

• Windows’ta py başlatıcısı kurulu sürümleri listeler ve seçmenizi sağlar.
• macOS ve Linux’ta python3 Python 3’ü, python ise sisteme göre farklı bir sürümü gösterebilir.
• Sanal ortam etkinleştirildiğinde python o ortamın yorumlayıcısına bağlanır ve belirsizlik ortadan kalkar.

Windows’ta kurulu sürümleri görmek için:

py --list

Sürümü proje bazında sabitlemek, kurulum kararlarının bireysel makinelere terk edilmemesi anlamına gelir. Sanal ortam bu karmaşayı proje sınırına hapseder; projeyi devralan geliştirici hangi sürümün beklendiğini tahmin etmek zorunda kalmaz.

pip ve “pip bulunamadı” hatası

pip, Python paketlerini kuran araçtır. pip komutu bulunamadığında en güvenilir çağrı biçimi, pip’i doğrudan çalıştırmak yerine yorumlayıcı üzerinden çağırmaktır:

python3 -m pip --version
python3 -m pip install --upgrade pip

Bu yöntem, paketin hangi Python’a kurulacağı konusunda belirsizlik bırakmaz. Windows’ta aynı komut py -m pip biçiminde yazılır.

Yeni dağıtımlarda sistem Python’una doğrudan paket kurmak engellenmiştir:

error: externally-managed-environment

Bu bir arıza değil, kasıtlı bir korumadır: dağıtım, kendi paket yöneticisiyle yönettiği dosyaların pip tarafından bozulmasını engeller. Çözüm sudo ile zorlamak değil, proje için sanal ortam oluşturmaktır. Sistem genelinde bir komut satırı aracı kurmak istiyorsanız pipx gibi izole ortam araçları bu iş için tasarlanmıştır.

Sanal ortam (venv) neden şart?

Sanal ortam, bir projenin paketlerini diğer projelerden ve sistem Python’undan ayıran izole bir dizindir:

python3 -m venv .venv

Etkinleştirmek için macOS ve Linux’ta:

source .venv/bin/activate

Windows PowerShell’de:

.venv\Scripts\Activate.ps1

Etkinleştirme sonrası terminal isteminde ortam adı görünür ve paketler bu dizine kurulur:

python -m pip install requests

Sanal ortamı şart kılan üç neden vardır: iki proje aynı paketin farklı sürümlerini gerektirdiğinde çakışma yaşanmaz; sistem Python’una yazılmadığı için işletim sistemi araçları bozulmaz; projeyi devralan geliştirici aynı bağımlılıkları aynı sürümlerle kurabilir.

En sık karşılaşılan 7 hata ve çözümü

ModuleNotFoundError: No module named …

Paket kurulu görünüyor ama Python bulamıyorsa, büyük olasılıkla başka bir yorumlayıcıya kurulmuştur. Sanal ortamın etkin olduğundan emin olun ve paketi python -m pip install biçiminde kurun. Kurulumun doğru yere gittiğini sys.executable çıktısıyla doğrulayın.

PermissionError: [Errno 13] Permission denied

Bu hata genelde paketi sistem dizinine kurmaya çalışmaktan kaynaklanır. Çözüm sudo eklemek değil, sanal ortam kullanmaktır. sudo ile pip çalıştırmak, sistem paket yöneticisinin yönettiği dosyaları bozarak ileride çok daha zor ayıklanan sorunlara yol açabilir.

SSL sertifika hatası

Bağlantıda sertifika doğrulama hatası alıyorsanız, ilk kontrol edilecek şey kurulumun sertifika paketini içerip içermediğidir. macOS’ta resmi kurulum paketiyle gelen Python, sertifikaların ayrı bir komutla kurulmasını gerektirebilir. Kurumsal ağda güvenlik duvarı veya vekil sunucu trafiği yeniden imzalıyorsa aynı hata çıkar; bu durumda kurumunuzun kök sertifikasını sisteme tanıtmak gerekir.

UnicodeDecodeError ve bozuk karakterler

Türkçe karakterler bozuk görünüyorsa dosyanın kodlaması belirtilmemiştir. Dosya işlemlerinde kodlamayı açıkça belirtin:

from pathlib import Path

text = Path("notlar.txt").read_text(encoding="utf-8")
print(text)

Kaynak dosyanın başına kodlama bildirimi eklemek de okunabilirliği artırır. Windows konsolunda çıktı bozuksa, konsolun kod sayfasını UTF-8’e çevirmek sorunu genelde ortadan kaldırır.

IndentationError ve TabError

Python blokları girintiyle tanımlar. Aynı dosyada sekme ve boşluk karakterlerinin karışması TabError üretir; eksik girinti IndentationError ile sonuçlanır. Editörünüzü sekmeyi dört boşluğa çevirecek şekilde ayarlamak bu hataları kalıcı olarak çözer.

Yanlış Python sürümünün çalışması

Kod beklediğiniz gibi davranmıyorsa çalışan yorumlayıcı beklediğiniz sürüm olmayabilir. Sürümü ve yorumlayıcı yolunu yazdırarak doğrulayın. Sanal ortam etkinleştirildiğinde bu belirsizlik ortadan kalkar.

pip paket derleme hatası

Bazı paketler kurulum sırasında derlenmeyi gerektirir. Windows’ta derleyici bulunamadığında kurulum yarıda kalır; paketin hazır derlenmiş sürümünü kullanmak ya da gerekli derleme araçlarını kurmak gerekir. Linux’ta eksik başlık dosyaları aynı hatayı üretir ve dağıtımın geliştirme paketlerini kurmak bunu çözer. Hata mesajının ilk satırları eksik bileşeni genelde açıkça söyler.

Editör kurulumu: VS Code

Kod yazmaya başlamak için Visual Studio Code yeterlidir. Kurulumdan sonra Python eklentisini yükleyin. Eklentinin en önemli işlevi, projede hangi yorumlayıcının kullanılacağını seçmenizi sağlamasıdır: komut paletinden yorumlayıcı seçme komutunu çalıştırıp sanal ortamın yorumlayıcısını seçin.

Editör içindeki terminal seçtiğiniz yorumlayıcıyı devralır, böylece komut satırındaki sürüm karışıklığı editörde tekrarlanmaz. Otomatik biçimlendirme ve girinti ayarlarını açık tutmak, girinti kaynaklı hataların büyük kısmını baştan engeller.

İlk proje önerisi

Kurulumu doğrulamanın en iyi yolu, küçük ama gerçek bir iş yapan bir betik yazmaktır. Bir klasördeki CSV dosyalarını okuyup satır sayısını yazdıran örnek iyi bir başlangıçtır:

import csv
from pathlib import Path

for path in sorted(Path(".").glob("*.csv")):
    with path.open(encoding="utf-8", newline="") as handle:
        rows = list(csv.DictReader(handle))
    print(f"{path.name}: {len(rows)} satır")

Bu betik dosya yolları, kodlama ve döngü kavramlarını tek yerde kullanır. Sonraki adımda aynı ortama bir web çatısı kurup küçük bir HTTP servisi yazmak, sanal ortam ve paket yönetimi pratiğini pekiştirir. Gerçek bir ihtiyaçtan yola çıkmak — her hafta elle hazırlanan bir raporu otomatikleştirmek gibi — öğrenmeyi hem hızlandırır hem kalıcı hale getirir.

Kurumsal tarafta Python genelde tek başına bir proje değil, mevcut sistemlere bağlanan bir otomasyon ve entegrasyon katmanı olarak değer üretir. Bu tür işler veri sahipliği ve sürdürülebilir bakım kararlarıyla birlikte planlanmayı gerektirir; yaklaşımı kurumsal yazılım çözümleri rehberimizde ayrıntılı ele alıyoruz. Sıfırdan geliştirilen bir otomasyon veya entegrasyon projesi için özel yazılım projelerimizi inceleyebilirsiniz.

Kontrol listesi

Kurulumu tamamladıktan sonra şu maddeleri doğrulayın:

• Yorumlayıcı sürümü komut satırından okunuyor.
• pip, yorumlayıcı üzerinden çağrılarak sürümünü bildiriyor.
• Her proje için ayrı bir sanal ortam oluşturuluyor.
• Sanal ortam etkinleştirildiğinde komut satırı istemi bunu gösteriyor.
• Editörde doğru yorumlayıcı seçili.
• Bağımlılıklar bir gereksinim listesinde kayıt altına alınıyor.
• Dosya işlemleri kodlama belirtilerek yapılıyor.
• Kurulum tercihleri, ekibe yeni katılan biri tekrar edebilsin diye kısa bir notta tutuluyor.

Bu maddelerin hepsi tamamsa ortam kaynaklı hataların büyük kısmı projenin başında elenmiş olur. Resmi ve güncel ayrıntılar için Python’un kurulum ve kullanım dokümantasyonu ile resmi indirme sayfası birincil kaynaklardır.

Sonraki adım

Python kurulumu doğru yapıldığında birkaç dakikalık bir iştir; asıl zaman kaybı PATH, sürüm ve sanal ortam kaynaklı belirsizliklerden doğar. Bu üç konuyu baştan netleştirmek, sonraki aylarda tekrar eden hata mesajlarını büyük ölçüde ortadan kaldırır. Kurulumu bir projeye bağlamadan önce yapay zekâ öğrenme rehberimizdeki araç ve kütüphane bölümüne, ilk kurumsal pilotu planlamak için dijital pazarlamada yapay zekâ rehberimize bakabilirsiniz.

Ekibiniz için Python tabanlı otomasyon, veri işleme veya entegrasyon katmanı kurmak istiyorsanız, grup şirketimiz Web Tasarım Ofisi web projelerinde teknik altyapı ve sürdürülebilir bakım desteği veriyor. Projenizin kapsamını konuşmak için bizimle iletişime geçebilirsiniz.