Python "pip install ." Komutu Ne İşe Yarar? Yerel Paket Kurulumu

Python'da pip install . komutu, bulunduğun klasördeki projeyi derleyip aktif Python ortamına kurar. Komut, proje klasöründeki tanım dosyasına (çoğunlukla pyproject.toml) ve paket yapısına bakarak çalışır. pip install . içindeki nokta, kurulacak projenin bulunduğun klasörde olduğunu belirtir. Böylece kendi yazdığın bir klasörü, sanki internetten indirilmiş bir kütüphaneymiş gibi her yerden import edebilirsin.

pip install . ne yapar ve hangi klasörde çalıştırılır?

pip install requests gibi bir komutta pip, adı verilen paketi bir paket dizininden indirir. pip install . komutunda ise indirilecek bir şey yoktur: pip, işaret ettiğin klasörü kaynak olarak alır, proje tanımındaki derleme bilgisine göre paketi hazırlar ve ortama kurar. Nokta, işletim sistemlerinde "şu anki klasör" anlamına gelir. Yani komut, hangi klasörde çalıştırıldığına göre farklı bir sonuç verir.

Bu yüzden komuttan önce doğru klasörde olduğundan emin olmalısın. cd ile proje klasörüne geç, sonra pwd (Windows'ta yalnızca cd) ile bulunduğun yolu, ls (Windows'ta dir) ile de klasörün içeriğini kontrol et. Listede pyproject.toml dosyasını görmüyorsan pip'in kuracağı bir şey bulamaz.

cd selamlasma-proje
pwd
ls

Beklenen çıktı (yol bilgisi bilgisayarına göre değişir):

/home/ogrenci/selamlasma-proje
pyproject.toml  selamlasma

Dosya listesinde hem pyproject.toml hem de paket klasörü görünüyorsa doğru yerdesin; pip install . komutunu artık çalıştırabilirsin. Bir üst klasörde ya da selamlasma klasörünün içindeyken çalıştırırsan pip aradığı dosyayı bulamaz ve hata verir.

Terminalde gezinmek ve temel Python sözdizimi sana henüz tam oturmadıysa önce ücretsiz Python bilgi testiyle seviyeni ölçebilirsin; paketleme konusu bu temelin üzerine kurulur.

pyproject.toml ne işe yarar? Minimal örnek

pyproject.toml, projenin kimlik ve derleme bilgilerini tutan tanım dosyasıdır. pip bu dosyadan projenin adını, sürümünü ve hangi araçla derleneceğini öğrenir. Aşağıdaki örnek yalnızca gerekli alanları içerir:

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "selamlasma-demo"
version = "0.1.0"

• [build-system]: Paketin nasıl derleneceğini anlatan bölümdür.
• requires: Derleme sırasında geçici olarak gereken araçların listesidir; burada setuptools.
• build-backend: pip'in derlemeyi hangi modüle devredeceğini söyler; setuptools için bu değer setuptools.build_meta olur.
• [project]: Projenin kimlik bilgilerinin durduğu bölümdür.
• name ve version: Projenin adı ve sürümüdür.

Bu örnekte yazar, lisans ya da bağımlılık listesi gibi isteğe bağlı alanları bilerek eklemedik; amaç önce çalışan en küçük kurulumu görmek. Klasör düzeni de sade tutuldu: proje klasörünün hemen altında içinde __init__.py bulunan tek bir paket klasörü var. Bu basit düzende setuptools paketi kendisi bulacaktır; proje büyüyüp birden fazla üst düzey klasör içerdiğinde hangi klasörlerin pakete dahil edileceğini yapılandırmada açıkça belirtmen gerekebilir.

Burada kafa karıştıran bir ayrım var: proje adı ile paket klasörü adı aynı şey olmak zorunda değildir. Kurarken ve kaldırırken proje adını kullanırsın: pip uninstall selamlasma-demo. Kodunda ise klasör adıyla çalışırsın: import selamlasma. Örneğimizde iki ad bilerek farklı seçildi; bu farkı ilk başta ayırt etmek, ilerideki "paket kurulu ama import edilmiyor" tarzı karışıklıkları azaltır.

Uygulama: selamlaşma paketini kur, başka klasörden import et

Bu bölümde küçük bir paket yazıp kuracaksın. Sonra paketin klasörünün dışındaki bir dosyadan onu çağıracaksın. Dosya yapısı şöyle olsun:

selamlasma_proje/
├── pyproject.toml
└── selamlasma/
    ├── __init__.py
    └── merhaba.py
deneme/
└── kullan.py

deneme/ klasörü proje klasörünün yanında, ayrı durur. Böylece kullan.py paketi yalnızca kurulum sayesinde bulabilir. Dosya içerikleri şunlardır:

# selamlasma_proje/pyproject.toml
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "selamlasma"
version = "0.1.0"

# selamlasma_proje/selamlasma/__init__.py
# (boş bırakabilirsin)

# selamlasma_proje/selamlasma/merhaba.py
def selam_ver(isim):
    return f"Merhaba, {isim}!"

# deneme/kullan.py
from selamlasma.merhaba import selam_ver

print(selam_ver("Ayşe"))

Önce kurulumsuz dene

Önce deneme klasörüne geçip dosyayı çalıştır:

cd deneme
python kullan.py

Beklenen sonuç bir hatadır:

ModuleNotFoundError: No module named 'selamlasma'

Python, çalıştırdığın dosyanın bulunduğu klasöre ve kurulu paketlerin yerine bakar. selamlasma bu yerlerin hiçbirinde olmadığı için bulunamaz.

Kur ve yeniden dene

Şimdi proje klasörüne geçip paketi kur, ardından deneme klasörüne dönüp aynı dosyayı çalıştır:

cd ../selamlasma_proje
python -m pip install .
cd ../deneme
python kullan.py

Bu kez çıktı şöyle olur:

Merhaba, Ayşe!

Kurulum paketi Python'un import için baktığı yerlerden birine kopyaladığı için, dosya hangi klasörde olursa olsun import çalışır. Modül, import ve fonksiyon kavramlarında takılırsan ücretsiz Sıfırdan Temel Python video eğitimi bu temelleri kendi hızında toparlamana yardımcı olabilir.

python -m pip neden tercih edilir ve sanal ortam kurulumu nereye yazar?

Sistemde birden fazla Python varsa, yalnızca pip yazdığında çalışan komut, kodu çalıştırdığın Python'dan farklı bir Python'a ait olabilir. Paket bu durumda beklediğinden başka bir ortama kurulur ve import yine hata verir. python -m pip biçimi pip'i, python komutunun gösterdiği yorumlayıcı üzerinden çalıştırır. Paketi kodu çalıştıracağın Python'a kurmuş olursun.

Kurulum, o anda kullanılan Python'ın site-packages klasörüne yazılır. Sanal ortam etkinse bu klasör ortamın içindedir. Etkin değilse paket sistem ya da kullanıcı ortamına gidebilir. Hangi Python'u kullandığını şu komutla görebilirsin:

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

Çıktıdaki yol .venv klasörünün içindeki python dosyasını gösteriyorsa sanal ortam etkindir. Sistemdeki bir yolu gösteriyorsa etkin değildir.

Sanal ortamda kurulum

Komutları selamlasma_proje klasöründe çalıştır:

python -m venv .venv

# Windows (PowerShell)
.venvScriptsActivate.ps1
# Windows (cmd)
.venvScriptsactivate.bat
# macOS / Linux
source .venv/bin/activate

python -m pip install .
python -m pip show selamlasma

pip show çıktısında Name: selamlasma ve Version: 0.1.0 satırlarını görürsün. Location satırı da paketin yazıldığı site-packages klasörünü gösterir. Bu yol .venv klasörünün altındaysa kurulum sanal ortama yapılmıştır.

Ortam değiştiğinde kurulum da değişir. Başka bir sanal ortamda ya da etkinleştirmediğin terminalde selamlasma görünmez. Orada paketi yeniden kurman gerekir. Terminali kapatıp açtığında sanal ortam etkin kalmaz, activate komutunu yeniden çalıştır.

pip install -e . ne zaman yeniden kurulum gerektirir? Karar tablosu

Editable kurulum (pip install -e .), paketin kopyalanmış bir sürümünü ortama koymaz. pip belgelerindeki yerel proje kurulumları sayfası bunu şöyle anlatır: proje dosyaları kopyalanmaz, geliştirme klasörü Python'un import yoluna eklenir. Kurulu paket, proje klasörünü işaret eder.

Bu yüzden mevcut .py dosyalarında yaptığın değişiklikler genellikle yeniden kurulum istemez. Aynı belgeye göre yeniden kurulum, projenin metadata bilgisi değiştiğinde gerekir. Sürüm numarası ya da oluşturulacak komut satırı betikleri bu bilgilere örnektir. Bağımlılık listesini ya da paket yapısını değiştirdiğinde de yeniden kurmak mantıklıdır.

Yeni bir modül ya da alt paket eklemenin editable modda nasıl davrandığı, proje yapılandırmasına ve kullandığın build backend'e göre değişir. Bu durumda tahmin yürütme, pip install -e . komutunu yeniden çalıştır. Zararsızdır ve emin olmanı sağlar.

Karar basit: kendi bilgisayarında geliştirirken -e, paketi başka bir yere teslim etmeden ya da paketlemeyi sınamadan önce normal kurulum kullan. Editable kurulum komutu şöyledir:

cd proje
python -m pip install -e .

Kurulum başarılı olursa pip, sonunda paketin adını içeren bir "Successfully installed" satırı yazar.

Sık klasör hataları ve kısa kontrol listesi

Paket kurulumunda sorunların çoğu kodda değil, komutun nerede ve hangi Python ile çalıştığında çıkar. Dört durumu sırayla kontrol et.

1. Yanlış klasördesin

pip, noktayı bulunduğun klasör olarak yorumlar ve orada proje tanımı arar. pyproject.toml yoksa pip bunun kurulabilir bir Python projesi olmadığını söyleyen bir hata verir. Mesajın tam metni sürüme göre değişebilir. Önce nerede olduğuna bak:

pwd
ls

Çıktıda pyproject.toml görmüyorsan cd ile doğru klasöre geç. Bir üst ya da alt klasörde olabilir.

2. Yanlış sanal ortam

Paket bir ortama kurulmuş, kodu başka ortamdaki Python çalıştırıyor olabilir. İkisini eşleştir:

python -m pip show selamlasma
python -c "import sys; print(sys.executable)"

pip show çıktısındaki Location satırı, sys.executable ile gösterilen Python'un ortamını işaret etmelidir. Paket hiç listelenmiyorsa bu Python'un ortamına kurulmamıştır.

3. Import kurulumsuz da çalışıyor gibi görünüyor

Python, import ararken çalıştığın klasörü de kullanır. Paket klasörünün yanından çalıştırırsan import selamlasma kurulum olmadan da başarılı olabilir. Kurulumun gerçekten işe yaradığını anlamak için komutu proje dışındaki başka bir klasörden çalıştır:

cd ~
python -c "import selamlasma; print(selamlasma.__file__)"

Normal kurulumda yol, ortamın site-packages klasörünü gösterir. Aşağıdaki yollar örnektir, sisteminde farklı görünebilir:

/home/ogrenci/.venv/lib/python3.12/site-packages/selamlasma/__init__.py

Editable kurulumda yol proje klasörüne çıkar:

/home/ogrenci/proje/selamlasma/__init__.py

Hata alırsan paket bu ortamda kurulu değildir ya da yanlış ortamdasın.

4. pip başka bir Python'dan çalışıyor

Çıplak pip komutu, sanal ortamdaki Python'dan farklı bir yorumlayıcıya ait olabilir. Önceki bölümde anlattığımız gibi python -m pip kullanırsan kurulum, o anda python dediğin yorumlayıcıya yapılır.

Kontrol listesi

• Komutu pyproject.toml dosyasının bulunduğu klasörde çalıştırıyorum (pwd ve ls ile baktım).
• pyproject.toml dosyasında proje adı ve paket tanımı var.
• Sanal ortam aktif; sys.executable beklediğim ortamı gösteriyor.
• Kurulumu python -m pip install . ya da python -m pip install -e . ile yaptım.
• python -m pip show paketi aynı ortamda listeliyor.
• Import testini proje dışındaki farklı bir klasörden çalıştırıp __file__ yoluna baktım.

Paketleme ve proje yapısını bir eğitmen eşliğinde adım adım pratik etmek istersen, Lise ve Üniversite öğrencileri için tasarlanmış birebir Python özel ders programı bu konuları kişiye özel müfredat içinde ele alabilir.

Sık Sorulan Sorular

pip install . ile kurduğum paketi nasıl kaldırırım?

Aynı ortam aktifken python -m pip uninstall paket-adi komutunu çalıştır. Buradaki ad, pyproject.toml içindeki name değeridir; import ettiğin klasör adıyla aynı olmayabilir. Hangi adla kurulduğundan emin değilsen önce python -m pip list çıktısına bak.

pip install . çalıştı ama kodu değiştirdim, kurulu sürüm neden eski kaldı?

Normal kurulum, kodun kurulum anındaki kopyasını ortama yazar. Sonradan proje klasöründe yaptığın değişiklikler o kopyaya yansımaz. Komutu yeniden çalıştırabilir ya da geliştirme boyunca python -m pip install -e . kullanabilirsin.

pyproject.toml olmadan pip install . çalışır mı?

pip, klasörde bir proje tanımı arar. Güncel yaklaşım pyproject.toml dosyasıdır; eski projelerde setup.py gibi dosyalar da görülür. Bunların hiçbiri yoksa pip klasörü kurulabilir bir proje olarak tanımaz. Sadece birkaç .py dosyan varsa önce minimal bir pyproject.toml yazman gerekir.

Bir paketi kurmak, kodunun nerede durduğunu ve hangi Python'un onu bulduğunu bilmek demektir. Klasörü, ortamı ve import yolunu kontrol etmeyi alışkanlık hâline getirirsen paketleme hatalarının çoğunu birkaç komutla çözebilirsin.