Python modülleri ve paketleri: import, pip, venv ve kütüphaneler sade anlatımla

Python'da modül, içinde kod bulunan bir dosyadır; import ise o dosyadan fonksiyon ve sınıf almanın yoludur. Modüllerden paketler, paketlerden kütüphaneler oluşur. Üçüncü taraf kütüphaneleri farklı projelerin birbirini bozmaması için sanal ortam (venv) içine kurarsınız. Bu yazıda tüm zinciri ele alıyoruz: import sırasında neler olduğunu, paketin nasıl yapılandığını, pip ve venv'in nasıl çalıştığını ve Python 3.15'in tembel (lazy) importlarını.

Modül, paket, kütüphane: farkları nedir

Günlük konuşmada "kütüphane", "paket" ve "modül" kelimeleri sıkça birbirinin yerine kullanılır; bu normaldir. Teknik olarak import her zaman bir modül ya da paketi yükler; pip ise PyPI'dan bir dağıtım kurar ve bu dağıtımın içinde paketler bulunur.

Python'da import nasıl çalışır

Gerçek kodda birkaç import biçimi görürsünüz:

import math                    # tüm modül, math.sqrt şeklinde kullanılır
from math import sqrt, pi      # yalnızca belirli adlar
import datetime as dt          # takma ad
from collections import Counter as C

print(math.sqrt(16), sqrt(9), pi)
print(dt.date.today())

Büyük kütüphaneler için takma adlar yaygındır: import numpy as np, import pandas as pd. from modul import * yazımından kaçının: ad alanını kirletir ve bir adın nereden geldiğini gizler.

import aslında ne yapar

1. Modülü sys.modules önbelleğinde arar. Zaten yüklüyse onu döndürür.
2. Yoksa sys.path listesindeki klasörlerde dosyayı arar: çalıştırılan betiğin klasörü, standart kütüphane ve ortamın site-packages klasörü.
3. Bulunan dosyayı baştan sona, yukarıdan aşağıya çalıştırır.
4. Modül nesnesini önbelleğe koyar ve bir adla ilişkilendirir.

Bundan iki pratik sonuç çıkar. Aynı modülü ikinci kez import etmek neredeyse bedavadır, kod yeniden çalıştırılmaz. Modülün en üst düzeyindeki her kod, print ve ağır hesaplamalar dahil, import sırasında çalışır.

import sys
for p in sys.path:
    print(p)
print("math" in sys.modules)

if __name__ == "__main__"

İmport dosyayı çalıştırdığına göre, "betik olarak çalıştırıldım" ile "içe aktarıldım" durumlarını ayırt etmek gerekir. Bunun için __name__ değişkeni vardır: dosya doğrudan çalıştırıldığında "__main__", import edildiğinde modül adına eşittir.

# kategoriler.py
def tahmin_et(baslik: str) -> str:
    return "yiyecek" if "kafe" in baslik.lower() else "diğer"

if __name__ == "__main__":
    print(tahmin_et("Evin yanındaki kafe"))   # yalnızca python kategoriler.py ile çalışır

Paketler için alternatif, içine __main__.py dosyası koyup python -m harcamalar komutuyla çalıştırmaktır.

Standart modüller

Python "pillerle birlikte" gelir: yüzlerce yerleşik modül kurulum gerektirmeden kullanılabilir. En yaygın olanlar:

Standart kütüphanenin modül listesi Python 3.10'dan beri sys.stdlib_module_names içinde tutulur. Bir modülde neler olduğunu dir(math) ve help(math) ile görebilirsiniz.

Kendi paketinizin yapısı

Modüller çoğaldığında bunları bir pakette toplarsınız. Yaygın düzen src-layout'tur:

harcama-projesi/
├── pyproject.toml
└── src/
    └── harcamalar/
        ├── __init__.py
        ├── cli.py
        ├── ayristirma.py
        ├── kategoriler.py
        └── rapor.py

Paket içindeki modüller birbirini ya paket adıyla (from harcamalar.kategoriler import tahmin_et) ya da göreli olarak (from .kategoriler import tahmin_et) import eder. Göreli import yalnızca paket içinde çalışır; dosya doğrudan betik olarak çalıştırılıyorsa çalışmaz.

pip ile Python kütüphanesi kurmak

Üçüncü taraf kütüphaneler PyPI deposunda bulunur; bunları Python ile birlikte gelen pip aracı kurar. En güvenli yol, pip'i doğrudan interpreter üzerinden çağırmaktır: kütüphane kodu çalıştırdığınız Python'a kesin olarak kurulur.

python -m pip install requests          # kur
python -m pip install "pandas>=2.3"     # sürüm sınırıyla
python -m pip install --upgrade requests
python -m pip uninstall requests        # kaldır
python -m pip list                      # kurulu paketleri listele
python -m pip show requests             # sürüm ve bağımlılıklar
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

Windows'ta python yerine çoğunlukla py başlatıcısı kullanılır. pip bulunamazsa, onu Python'un kendi modülü kurar: python -m ensurepip --upgrade.

Popüler Python kütüphaneleri

PyPI'de yüz binlerce paket var, ama çoğu projede aynı kısa liste görülür. Egzotik paketlere bakmadan önce bu listeden başlamak iyidir.

Dikkat: kurulacak ad ile içe aktarma adı her zaman aynı değildir. pip install pillow deyip from PIL import Image yazarsınız; opencv-python kurulur, ama cv2 olarak içe aktarılır. Kurulumdan hemen sonra import hata veriyorsa, paketin belgelerinde içe aktarma adına bakın.

Linux'ta kütüphane kurulumu

Yeni Debian ve Ubuntu sürümlerinde sistem Python'una pip install yapmaya çalışırsanız externally-managed-environment hatası alırsınız (PEP 668). Bu bir korumadır: sistem Python'u işletim sisteminin paket yöneticisine aittir ve pip'in onu bozmaması gerekir. Doğru çözüm --break-system-packages değil, bir sanal ortamdır.

venv: sanal ortam

Sanal ortam, kendi Python bağlantısına ve kendi site-packages klasörüne sahip ayrı bir klasördür. İçine kurulan kütüphaneler yalnızca o projede görünür. Böylece bir projede Django 4, diğerinde Django 5 kullanabilirsiniz; ikisi çakışmaz.

venv modülü Python ile birlikte gelir, ayrıca kurmanız gerekmez (Debian/Ubuntu'da bazen python3-venv sistem paketi gerekir).

# .venv klasöründe ortam oluştur
python -m venv .venv

# etkinleştir: Linux ve macOS
source .venv/bin/activate
# etkinleştir: Windows PowerShell
.venv\Scripts\Activate.ps1

# artık pip paketleri .venv içine kurar
python -m pip install requests
python -c "import sys; print(sys.prefix)"

# ortamdan çık
deactivate

Etkinleştirdikten sonra terminal satırının başında (.venv) belirir. Ortam klasörünü git'e eklemeyin (.gitignore dosyasına .venv/ yazın) ve makineler arasında taşımayın; bunun yerine bağımlılık listesini saklayıp ortamı yeniden kurun. PowerShell etkinleştirme betiğini engelliyorsa, kullanıcı için izin verin: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

uv ve pyproject.toml

Modern projeler bağımlılıklarını pyproject.toml dosyasında tanımlar. Kursta kullanılan uv yöneticisi ortam oluşturmayı ve kurulumu birleştirir: uv add pandas paketi indirir, pyproject.toml dosyasına yazar ve kesin sürümleri uv.lock dosyasına kaydeder. Bir meslektaşınız projeyi klonlayıp uv sync çalıştırdığında birebir aynı ortamı elde eder.

[project]
name = "harcamalar"
version = "0.1.0"
requires-python = ">=3.15"
dependencies = [
    "pandas>=2.3",
]

[project.scripts]
harcamalar = "harcamalar.cli:main"

Python 3.15'te tembel importlar (PEP 810)

Bu konudaki en önemli yenilik 3.15'teki lazy anahtar sözcüğüdür. Ağır kütüphaneler yüklenmesi uzun süren modüllerdir: kursun ölçümünde python:3.15-slim imajında sıradan import pandas yaklaşık 415 ms sürdü, lazy import pandas ise yaklaşık 13 ms. --help için çalıştırılan bir komut satırı aracında bu fark çok büyüktür.

lazy import pandas as pd
lazy from harcamalar.rapor import rapor_olustur

def main() -> None:
    ...
    df = pd.read_csv(path)   # pandas gerçekten yüklenir — yalnızca burada

Modül yerine ad, bir vekil nesneye (types.LazyImportType) bağlanır; gerçek import ilk kullanımda yapılır. O ada hiç dokunulmazsa zaman hiç harcanmaz.

Tembel importların kısıtları

• Yalnızca modülün en üst düzeyinde kullanılabilir: fonksiyon, sınıf ya da try/except içinde yazılırsa SyntaxError alırsınız.
• lazy from x import * yasaktır.
• ModuleNotFoundError başlangıçta değil, adın ilk kullanımında ortaya çıkar.
• Modülün yan etkileri (eklenti kaydı vb.) zamanda kayar.

Tüm importları tembel yapmak için -X lazy_imports=all bayrağı ya da PYTHON_LAZY_IMPORTS=all ortam değişkeni kullanılabilir; istisnalar sys.set_lazy_imports_filter() ile belirlenir. Eski sürümlerde de çalışması gereken kod için modülde __lazy_modules__ = ["pandas"] tanımlanabilir: 3.15 bu importları tembel yapar, eski sürümler ise normal import yapar. Başlangıçta zamanın nereye gittiğini python -X importtime -c "import pandas" gösterir. En çok fayda, sık ve kısa süreli çalışan programlarda görülür; uzun süre çalışan bir sunucuda neredeyse hiçbir fark yaratmaz.

Tipik hatalar

• ModuleNotFoundError: No module named 'requests' — kütüphane başka bir Python'a kurulmuş ya da ortam etkinleştirilmemiş. Aynı interpreter ile python -m pip show requests komutunu çalıştırın.
• Kendi dosyanız json.py, random.py ya da csv.py adını taşıyor — betik klasörü sys.path listesinde ilk sırada olduğundan standart modülün önüne geçer. Python 3.13+ hata mesajında "consider renaming" önerir. Dosyayı yeniden adlandırın ve __pycache__ klasörünü silin.
• Döngüsel import: a.py, b.py'yi; b.py de a.py'yi import eder. Ortak kodu üçüncü bir modüle taşıyın ya da import'u fonksiyonun içine alın.
• pip, Python prompt'unun içinde çalıştırılmış (>>> pip install) — bu bir SyntaxError verir. pip komutları terminalde çalıştırılır.

Özet

Modül bir dosya, paket bir modül klasörü, kütüphane ise bunların hazır bir setidir; import modülü önbellekte ve sys.path üzerinde arar ve bir kez çalıştırır. Üçüncü taraf kütüphaneleri yalnızca pip ya da uv ile venv sanal ortamına kurun: projeler birbirini bozmaz ve ortam kolayca yeniden oluşturulur. Kursta bu konu uygulamalı işlenir: harcama takipçisi bağımlılıkları olan bir pakete dönüşür ve tembel importlar sayesinde hızlı başlar.