Python pathlib: Path ile Dosya Yolları, glob, mkdir ve copy

Saf yollar ve somut yollar

pathlib sınıfları iki aileye ayrılır. Saf yollar (PurePath, PurePosixPath, PureWindowsPath) yalnızca metin üzerinde hesap yapar, dosya sistemine hiç dokunmaz. Somut yollar (Path, PosixPath, WindowsPath) saf yollardan türer ve bunlara ek olarak dosya sistemi işlemleri sunar. Path(...) yazdığınızda Windows'ta bir WindowsPath, Linux ve macOS'ta bir PosixPath elde edersiniz. Saf sınıflar iki durumda işe yarar: Linux sunucuda Windows yollarını işlemek (orada WindowsPath oluşturulamaz ama PureWindowsPath oluşturulabilir) ya da kodunuzun gerçekten dosya sistemine erişmediğinden emin olmak.

from pathlib import Path, PureWindowsPath

yol = Path("proje") / "veri" / "kullanicilar.json"
print(repr(yol))
print(str(yol))
print(yol.as_posix())

w = PureWindowsPath(r"C:\Users\ayse\Belgeler\rapor.docx")
print(w.drive, w.anchor, w.name)
print(w.as_posix())
# çıktı: WindowsPath('proje/veri/kullanicilar.json')
# çıktı: proje\veri\kullanicilar.json
# çıktı: proje/veri/kullanicilar.json
# çıktı: C: C:\ rapor.docx
# çıktı: C:/Users/ayse/Belgeler/rapor.docx

Bu örnek Windows'ta çalıştırıldı; Linux'ta ilk satır PosixPath('proje/veri/kullanicilar.json'), ikinci satır eğik çizgili olurdu. str() yolun işletim sistemindeki doğal biçimini (Windows'ta ters eğik çizgili) verir, as_posix() ise her zaman / kullanır. Yol nesneleri os.PathLike protokolünü uyguladığı için open() dahil yol bekleyen hemen her fonksiyona doğrudan verilebilir; ayrıca str() ile çevirmeniz gerekmez.

/ operatörü ile yol birleştirme

/ operatörü os.path.join() işlevini görür: sol taraf bir yol nesnesi ya da (sağ taraf yol nesnesiyse) bir metin olabilir. Dikkat edilmesi gereken kural şudur: birleştirilen parçalardan biri mutlak bir yolsa, ondan önceki her şey atılır. Kullanıcıdan gelen bir dosya adını bir klasörle birleştirirken bu, beklemediğiniz bir yere yazmanıza yol açabilir:

from pathlib import PurePosixPath

kok = PurePosixPath("/srv/uygulama")
print(kok / "yuklemeler" / "foto.png")
print("/etc" / PurePosixPath("hosts"))
print(kok / "/tmp/baska.txt")
print(kok.joinpath("a", "b.txt"))
# çıktı: /srv/uygulama/yuklemeler/foto.png
# çıktı: /etc/hosts
# çıktı: /tmp/baska.txt
# çıktı: /srv/uygulama/a/b.txt

Yolun parçaları: name, stem, suffix, parent

Bir yolun bileşenlerini metin işlemiyle ayırmak yerine özelliklerini kullanın. name son bileşeni, suffix son uzantıyı, suffixes tüm uzantıları, stem son uzantı çıkarılmış adı, parent bir üst klasörü, parents ise tüm üst klasörleri verir. Bunlar tamamen sözcüksel (lexical) işlemlerdir; dosyanın var olup olmadığına bakılmaz:

from pathlib import PurePosixPath

p = PurePosixPath("/srv/site/static/logo.tar.gz")
print(p.name, p.stem, p.suffix, p.suffixes, sep=" | ")
print(p.parent)
print(p.parts)
print([str(x) for x in p.parents])
print(PurePosixPath("dosya.").suffix, PurePosixPath("README").suffix == "")
# çıktı: logo.tar.gz | logo.tar | .gz | ['.tar', '.gz']
# çıktı: /srv/site/static
# çıktı: ('/', 'srv', 'site', 'static', 'logo.tar.gz')
# çıktı: ['/srv/site/static', '/srv/site', '/srv', '/']
# çıktı: . True

Son satırdaki ayrıntı Python 3.14 değişikliğidir: belgelere göre tek bir nokta artık geçerli bir uzantı sayılır, bu yüzden "dosya." adının suffix değeri "." olur. Uzantısız bir dosyada suffix boş metindir. Yine sözcüksel olduğu için PurePosixPath("foo/..").parent sonucu foo çıkar; gerçek dosya sisteminde yukarı çıkmak istiyorsanız önce resolve() çağırın.

Yeni bir yol türetmek için üç metot vardır: with_name() son bileşeni, with_stem() uzantıyı koruyup adı, with_suffix() uzantıyı değiştirir. with_suffix("") uzantıyı kaldırır. Yol nesneleri değişmez (immutable) olduğu için bu metotlar her zaman yeni bir nesne döndürür:

from pathlib import PurePosixPath

p = PurePosixPath("raporlar/2026/ocak.taslak.md")
print(p.with_name("subat.md"))
print(p.with_stem("ocak.final"))
print(p.with_suffix(".html"))
print(p.with_suffix(""))
print(p)
# çıktı: raporlar/2026/subat.md
# çıktı: raporlar/2026/ocak.final.md
# çıktı: raporlar/2026/ocak.taslak.html
# çıktı: raporlar/2026/ocak.taslak
# çıktı: raporlar/2026/ocak.taslak.md

Dosya ve klasör sorgulama

Somut yollarda exists(), is_file() ve is_dir() yolun durumunu sorgular. Python 3.14 ile bu metotlar işletim sisteminden gelen herhangi bir OSError durumunda hata fırlatmak yerine False döndürmeye başladı; bu, os.path.exists() ile tutarlı bir davranıştır. Hatayı bastırmadan dosya bilgisi almak isterseniz stat() kullanılır; st_size bayt cinsinden boyutu, st_mtime son değiştirilme zamanını verir:

from pathlib import Path

ayar = Path("ayarlar.ini")
print(ayar.exists())
ayar.write_text("[genel]\ndil = tr\n", encoding="utf-8")
print(ayar.exists(), ayar.is_file(), ayar.is_dir())
print(ayar.stat().st_size)
print(Path(".").is_dir())
# çıktı: False
# çıktı: True True False
# çıktı: 19
# çıktı: True

Dosyanın boyutu 19 bayt çıktı; örneği Windows'ta çalıştırdık ve metin modunda iki \n karakteri \r\n olarak yazıldı. Linux'ta aynı içerik 17 bayt olur. Bu farkın nedenini dosya okuma ve yazma yazısındaki satır sonu bölümünde anlattık.

Okuma ve yazma kısayolları

read_text(), write_text(), read_bytes() ve write_bytes() dosyayı açar, işlemi yapar ve kapatır; kısa dosyalar için with open(...) yazmaktan daha pratiktir. write_text() ve write_bytes() var olan dosyanın üzerine yazar ve yazılan karakter ya da bayt sayısını döndürür. Metin metotları open() ile aynı encoding, errors ve newline parametrelerini kabul eder. Büyük dosyaları satır satır işlemek ya da sona ekleme yapmak için Path.open() kullanılır:

from pathlib import Path

not_dosyasi = Path("not.txt")
print(not_dosyasi.write_text("Çarşamba toplantı\n", encoding="utf-8"))
print(not_dosyasi.read_text(encoding="utf-8"), end="")

with not_dosyasi.open("a", encoding="utf-8") as f:
    f.write("Perşembe teslim\n")
print(not_dosyasi.read_text(encoding="utf-8").splitlines())

Path("logo.bin").write_bytes(b"\x89PNG")
print(Path("logo.bin").read_bytes())
# çıktı: 18
# çıktı: Çarşamba toplantı
# çıktı: ['Çarşamba toplantı', 'Perşembe teslim']
# çıktı: b'\x89PNG'

Klasör oluşturma ve silme

mkdir() varsayılan olarak tek bir klasör oluşturur: klasör zaten varsa FileExistsError, üst klasörlerden biri yoksa FileNotFoundError verir. parents=True eksik üst klasörleri de oluşturur (POSIX'teki mkdir -p gibi), exist_ok=True ise klasör zaten varsa hata vermez. İkisi birlikte, "bu klasör yapısı olsun" demenin güvenli yoludur:

from pathlib import Path

for deneme in (lambda: Path("arsiv").mkdir(), lambda: Path("arsiv").mkdir(),
               lambda: Path("a/b/c").mkdir()):
    try:
        deneme()
        print("oluşturuldu")
    except OSError as e:
        print(type(e).__name__)

hedef = Path("cikti/2026/kasim")
hedef.mkdir(parents=True, exist_ok=True)
hedef.mkdir(parents=True, exist_ok=True)
print(hedef.is_dir())
# çıktı: oluşturuldu
# çıktı: FileExistsError
# çıktı: FileNotFoundError
# çıktı: True

Python 3.15, parents=True ile oluşturulan ara klasörlerin izinlerini ayrıca belirlemek için mkdir() metoduna parent_mode parametresini ekledi; aynı parametre os.makedirs() fonksiyonuna da geldi. Silme tarafında unlink() dosya ya da sembolik bağlantı siler; dosya yoksa FileNotFoundError verir, missing_ok=True ile bu hata yok sayılır. rmdir() yalnızca boş klasörleri siler; dolu bir klasörde OSError alırsınız:

from pathlib import Path

klasor = Path("gecici")
klasor.mkdir()
(klasor / "a.txt").write_text("a", encoding="utf-8")
try:
    klasor.rmdir()
except OSError as e:
    print("rmdir:", type(e).__name__)

(klasor / "a.txt").unlink()
(klasor / "a.txt").unlink(missing_ok=True)
klasor.rmdir()
print(klasor.exists())
# çıktı: rmdir: OSError
# çıktı: False

Bir klasörü içindekilerle birlikte silmek için pathlib'te tek bir metot yoktur; bunun için shutil.rmtree() kullanılır. Bu fonksiyon geri dönüşü olmayan bir silme yapar, yolu iki kez kontrol edin.

Klasör içeriğini listeleme: iterdir, glob, rglob

iterdir() bir klasörün doğrudan içeriğini yol nesneleri olarak üretir; sıra belirsizdir ve . ile .. dahil edilmez. glob(desen) klasörde kabuk tarzı bir desenle eşleşen yolları, rglob(desen) ise aynı aramayı tüm alt klasörlerde yapar (başına **/ eklemekle aynıdır). Belgeler sonuçların belirli bir sırada gelmediğini vurgular; tutarlı çıktı için sorted() kullanın:

from pathlib import Path

kok = Path("site")
for dosya in ["index.html", "css/ana.css", "css/tema.css", "js/app.js", "js/lib/yardim.js"]:
    yol = kok / dosya
    yol.parent.mkdir(parents=True, exist_ok=True)
    yol.write_text("", encoding="utf-8")

print(sorted(p.name for p in kok.iterdir()))
print(sorted(p.as_posix() for p in kok.glob("*/*.css")))
print(sorted(p.as_posix() for p in kok.rglob("*.js")))
print(sorted(p.as_posix() for p in kok.glob("**/")))
print(len(list(kok.glob("**/*"))))
# çıktı: ['css', 'index.html', 'js']
# çıktı: ['site/css/ana.css', 'site/css/tema.css']
# çıktı: ['site/js/app.js', 'site/js/lib/yardim.js']
# çıktı: ['site', 'site/css', 'site/js', 'site/js/lib']
# çıktı: 8

Desen dilinde * bir bileşenin içinde ayırıcı olmayan herhangi bir karakter dizisiyle, ? tek karakterle, [abc] köşeli parantezdeki karakterlerden biriyle eşleşir; tam bir bileşen olarak yazılan ** ise sıfır ya da daha fazla klasör seviyesi demektir. Desen / ile biterse yalnızca klasörler döner. Python 3.13 itibarıyla ** ile biten desenler hem dosyaları hem klasörleri döndürür (önceden yalnızca klasörler gelirdi). glob modülünden farklı olarak pathlib nokta ile başlayan gizli dosyaları özel saymaz ve ** sembolik bağlantıları varsayılan olarak izlemez. Ayrıca tarama sırasında oluşan OSError hataları (örneğin okuma izni olmayan klasörler) sessizce atlanır.

Python 3.14 ile gelen info özelliği, iterdir() ile üretilen yollarda klasör taraması sırasında öğrenilen dosya türü bilgisini önbellekte tutar; p.info.is_dir() çoğu durumda ek bir sistem çağrısı yapmadan cevap verir. Bir yolun bir desene uyup uymadığını dosya sistemine bakmadan test etmek için de 3.13'te gelen full_match() metodu vardır: PurePath("a/b.py").full_match("a/*.py") sonucu True olur.

Ağaç gezme: Path.walk()

Python 3.12 ile gelen walk(), os.walk() gibi bir klasör ağacını gezer ve her klasör için (klasör_yolu, alt_klasör_adları, dosya_adları) üçlüsü üretir. Varsayılan yukarıdan aşağı gezmede alt_klasör_adları listesini yerinde değiştirerek bazı dalları atlayabilirsiniz. Belgelere göre listelerin sıralı olup olmadığı dosya sistemine bağlıdır, bu yüzden örnekte sıralıyoruz:

from pathlib import Path

for dosya in ["proje/main.py", "proje/__pycache__/main.pyc", "proje/lib/araclar.py", "proje/lib/veri.json"]:
    Path(dosya).parent.mkdir(parents=True, exist_ok=True)
    Path(dosya).write_text("x", encoding="utf-8")

for kok, klasorler, dosyalar in Path("proje").walk():
    klasorler[:] = sorted(k for k in klasorler if k != "__pycache__")
    print(kok.as_posix(), sorted(dosyalar))
# çıktı: proje ['main.py']
# çıktı: proje/lib ['araclar.py', 'veri.json']

walk() sembolik bağlantıları varsayılan olarak izlemez ve klasörlere giden bağlantıları dosya listesine koyar; bu, onu os.walk()'tan ayıran bir noktadır. os.scandir() hataları varsayılan olarak yok sayılır; on_error parametresine bir fonksiyon verirseniz her OSError ona iletilir.

Göreli, mutlak ve çözümlenmiş yollar

absolute() yolu geçerli çalışma klasörüne göre mutlak yapar ama .. bileşenlerine dokunmaz. resolve() ise sembolik bağlantıları çözer ve belgelere göre .. bileşenlerini ortadan kaldıran tek metottur. relative_to() bir yolu başka bir yola göre ifade eder; mümkün değilse ValueError verir. Python 3.12'den beri walk_up=True ile .. eklenerek yukarı çıkılmasına izin verilebilir:

from pathlib import Path, PurePosixPath

p = Path("a/../b.txt")
print(p.absolute().parts[-3:])
print(p.resolve() == Path.cwd() / "b.txt")

dosya = PurePosixPath("/etc/nginx/sites/site.conf")
print(dosya.relative_to("/etc/nginx"))
print(dosya.is_relative_to("/var"))
print(dosya.relative_to("/etc/ssl", walk_up=True))
try:
    dosya.relative_to("/var")
except ValueError as e:
    print(e)
# çıktı: ('a', '..', 'b.txt')
# çıktı: True
# çıktı: sites/site.conf
# çıktı: False
# çıktı: ../nginx/sites/site.conf
# çıktı: '/etc/nginx/sites/site.conf' is not in the subpath of '/var'

Betiklerde en sık ihtiyaç duyulan kalıp, betiğin kendi klasöründeki bir dosyaya ulaşmaktır. open("veri.json") geçerli çalışma klasörüne göre çözülür ve programı başka bir klasörden çalıştırdığınızda dosyayı bulamaz. Path(__file__).resolve().parent / "veri.json" ise her zaman betiğin yanındaki dosyayı gösterir. Path.home() kullanıcının ev klasörünü, Path.cwd() geçerli klasörü, expanduser() ise ~ işaretini açar.

Kopyalama, taşıma ve yeniden adlandırma

rename(hedef) ve replace(hedef) dosya ya da klasörü yeniden adlandırır ve yeni yolu döndürür. Fark hedef zaten varsa ortaya çıkar: belgelere göre rename() Unix'te var olan bir dosyanın üzerine sessizce yazar ama Windows'ta FileExistsError verir; replace() ise her sistemde var olan dosyayı ya da boş klasörü koşulsuz değiştirir. Göreli hedefler yol nesnesinin klasörüne değil, geçerli çalışma klasörüne göre yorumlanır.

Python 3.14 öncesinde kopyalama için mutlaka shutil gerekiyordu. 3.14 ile Path sınıfına dört metot eklendi: copy(hedef) bir dosyayı ya da klasör ağacını hedefe kopyalar, copy_into(klasör) var olan bir klasörün içine kopyalar, move(hedef) ve move_into(klasör) taşır. Hepsi yeni konumu gösteren bir Path döndürür. move() aynı dosya sisteminde os.replace() kullanır, farklı dosya sistemleri arasında ise kopyalayıp kaynağı siler:

from pathlib import Path

Path("taslak.txt").write_text("içerik", encoding="utf-8")
Path("yedek").mkdir()

kopya = Path("taslak.txt").copy("taslak_kopya.txt")
icine = Path("taslak.txt").copy_into("yedek")
tasinan = kopya.move("yedek/eski.txt")
yeni_ad = Path("taslak.txt").rename("son.txt")

print(icine.as_posix(), tasinan.as_posix(), yeni_ad.as_posix())
print(sorted(p.name for p in Path("yedek").iterdir()))
print(Path("taslak.txt").exists(), Path("taslak_kopya.txt").exists())
# çıktı: yedek/taslak.txt yedek/eski.txt son.txt
# çıktı: ['eski.txt', 'taslak.txt']
# çıktı: False False

copy() varsayılan olarak yalnızca klasör yapısını ve dosya verisini kopyalamayı garanti eder; izinler ve zaman damgaları gibi üst verileri de taşımak için preserve_metadata=True verin. Kodunuz 3.14 öncesi sürümlerde de çalışacaksa shutil.copy2(), shutil.copytree() ve shutil.move() aynı işleri yapar.

os.path ve shutil karşılıkları

Eski kodlarda sık gördüğünüz os.path fonksiyonlarının pathlib karşılıkları belgelerde bir tabloyla verilir. Belgeler önemli bir uyarı da ekler: pathlib, os.path'in birebir yerine geçmez. Örneğin Path("klasor/") sondaki eğik çizgiyi atar ve Path("./program") başındaki ./ kısmını kaldırır; bu, yolu bir komuta ya da alt sürece verirken anlamını değiştirebilir. os.path.abspath() .. bileşenlerini kaldırırken Path.absolute() onları güvenlik için korur.

Belgeler performans konusunda da açıktır: os ve os.path büyük ölçüde C ile yazılmıştır ve hızlıdır, pathlib ise saf Python'dur ve çoğu zaman daha yavaştır, ama bu fark nadiren önem taşıyacak kadar büyüktür. Python 3.15 ayrıca uzun süredir kullanımdan kaldırılmış olan PurePath.is_reserved() metodunu tamamen sildi; Windows'ta ayrılmış adları (örneğin NUL) tespit etmek için os.path.isreserved() kullanılır.

Uygulama: dosyaları uzantısına göre klasörlemek

İndirilenler klasörü gibi karışık bir klasördeki dosyaları uzantılarına göre alt klasörlere taşıyan küçük bir araç yazalım. Uzantısız dosyalar "diger" klasörüne gidiyor; suffix.lower() sayesinde .JPG ile .jpg aynı klasörde toplanıyor:

from pathlib import Path

kaynak = Path("indirilenler")
kaynak.mkdir()
for ad in ["tatil.JPG", "fatura.pdf", "kapak.jpg", "notlar", "sunum.pdf"]:
    (kaynak / ad).write_bytes(b"")

for dosya in sorted(kaynak.iterdir()):
    if not dosya.is_file():
        continue
    uzanti = dosya.suffix.lower().lstrip(".") or "diger"
    hedef = kaynak / uzanti
    hedef.mkdir(exist_ok=True)
    dosya.move_into(hedef)

for klasor in sorted(kaynak.iterdir()):
    print(klasor.name, sorted(p.name for p in klasor.iterdir()))
# çıktı: diger ['notlar']
# çıktı: jpg ['kapak.jpg', 'tatil.JPG']
# çıktı: pdf ['fatura.pdf', 'sunum.pdf']

Döngüye girmeden önce sorted(kaynak.iterdir()) ile listeyi bir kez sabitledik. Belgelere göre yineleyici oluşturulduktan sonra klasöre eklenen ya da silinen dosyaların sonuca dahil olup olmayacağı belirsizdir; içeriği değiştirdiğiniz bir klasörü gezerken listeyi önceden almak bu belirsizliği ortadan kaldırır.

Sık yapılan hatalar

• Yolları metin birleştirmeyle kurmak: "klasor" + "/" + ad Windows ve Linux arasında tutarsızlık yaratır; Path("klasor") / ad kullanın.
• Mutlak parçanın öncesini sileceğini unutmak: kok / "/etc/passwd" sonucu kok'u yok sayar; kullanıcıdan gelen adları birleştirmeden önce doğrulayın.
• glob sonucunu sıralı sanmak: Sıra belirsizdir; çıktı tutarlı olmalıysa sorted() kullanın.
• exists() sonrası işlem yapmak: Kontrol ile işlem arasında dosya değişebilir; mümkünse işlemi doğrudan yapıp hatayı yakalayın ya da exist_ok ve missing_ok gibi parametreleri kullanın.
• rmdir() ile dolu klasör silmeye çalışmak: Yalnızca boş klasörler silinir; ağaç için shutil.rmtree() gerekir.
• rename() ile üzerine yazmayı beklemek: Windows'ta hedef varsa FileExistsError alırsınız; her sistemde aynı davranış için replace() kullanın.
• Göreli yolu betik klasörüne göre sanmak: Göreli yollar geçerli çalışma klasörüne göre çözülür; Path(__file__).resolve().parent ile başlayın.

Sık Sorulan Sorular

pathlib mi os.path mi kullanmalıyım?

Yeni kod için pathlib daha okunur bir nesne yönelimli arayüz sunar ve belgelerin ilk önerisidir. bytes yollar, klasör tanıtıcısına göre göreli yollar ya da sondaki eğik çizginin anlam taşıdığı durumlar için os ve os.path fonksiyonları gerekebilir.

Bir klasördeki tüm .txt dosyalarını nasıl bulurum?

Yalnızca o klasörde aramak için Path("klasor").glob("*.txt"), alt klasörler dahil aramak için Path("klasor").rglob("*.txt") kullanın. Sonuçları sıralı istiyorsanız sorted() ile sarın.

Dosya uzantısını nasıl değiştiririm?

p.with_suffix(".yeni") yeni bir yol döndürür; diskteki dosyayı değiştirmek için bunu p.rename(p.with_suffix(".yeni")) biçiminde kullanın.

Path nesnesini open() fonksiyonuna verebilir miyim?

Evet. open() yol benzeri (path-like) nesneleri kabul eder; ayrıca p.open() metodu da aynı parametrelerle çalışır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Python öğrenme rehberi · Python dosya okuma ve yazma · Python with ve context manager · Python argparse · Python json modülü · Python generator ve iterator · Linux nedir