Uv: Bağımlılıkları olan betikleri çalıştırmak

 (docs.astral.sh)
14 puan yazan GN⁺ 2025-07-22 | 7 yorum | WhatsApp'ta paylaş
  • uv, Python betiklerini çalıştırırken bağımlılık yönetimini otomatikleştirir
  • Ayrı bir sanal ortam yönetimi olmadan, her betik için ortam otomatik olarak oluşturulur ve korunur
  • Gerekli paketler inline metadata veya komut satırı seçenekleri gibi çeşitli yöntemlerle bildirilebilir
  • Python sürümü ve paket yönetimi de betik bazında bildirilebilir ve otomatik olarak ayarlanabilir
  • Lock dosyaları ve bağımlılık sürüm kısıtlama seçenekleriyle yeniden üretilebilirlik ve bakım kolaylığı artar

Genel Bakış

  • uv, Python betiklerini çalıştırırken o betiğin ihtiyaç duyduğu paket bağımlılıklarını otomatik olarak yöneten bir araçtır
  • Kullanıcının zahmetli sanal ortam oluşturma ve paket kurma işlemlerini elle yapması gerekmez
  • Çeşitli çalıştırma seçenekleri, inline metadata kullanımı, farklı bağımlılık bildirim yöntemleri ve çeşitli kontrol özellikleri sunar

Python ortamı ve uv'nin rolü

  • Python, her kurulum için kendine özgü bir ortama sahiptir
  • Genel olarak sanal ortam oluşturmak ve yönetmek tavsiye edilir
  • uv, sanal ortamları otomatik olarak yönetir ve bağımlılıkları bildirimsel bir yaklaşımla ele alır
  • Basit betikler uv run example.py ile anında çalıştırılabilir
  • Standart kütüphane kullanıldığında ek yapılandırma olmadan çalışır

Argüman iletimi ve girdi yöntemleri

  • Betiğe komut satırı argümanları geçirilebilir
  • Standart girdiden doğrudan betik kodu alarak çalıştırabilir; ayrıca here-document özelliğini de destekler

Proje ortamı ve --no-project seçeneği

  • Betik bir proje klasöründe (pyproject.toml bulunan bir yer gibi) çalıştırılırsa, proje bağımlılıkları da kurulur
  • Buna gerek yoksa, --no-project bayrağı betik adından önce eklenerek proje ortamı yok sayılabilir

Betik bağımlılıklarını bildirme ve yönetme

  • Harici paketler gerekiyorsa, komut satırı seçeneği --with kullanılarak bağımlılıklar belirtilip çalıştırılabilir
  • Belirli sürüm kısıtları da desteklenir ve birden fazla bağımlılık seçenek tekrar edilerek belirtilebilir
  • Proje ortamına ek bağımlılıklar eklenebilir; istenmiyorsa --no-project ile kontrol edilebilir

Inline Script Metadata (PEP 723 yöntemi)

  • Python artık betiğin içinde bağımlılıkları veya Python sürümünü bildirmek için standart bir biçimi destekliyor
  • uv init --script ile inline metadata içeren bir betik kolayca oluşturulabilir
  • uv add --script ile betik için gerekli bağımlılıklar TOML biçiminde eklenip yönetilebilir
  • Inline metadata varsa, proje bağımlılıkları yok sayılır ve yalnızca betiğin bağımlılıkları uygulanır

Python sürümünü bildirme ve yönetme

  • Betiğin içinde veya çalıştırma sırasında istenen Python sürümü belirtilebilir
  • Belirtilen sürüm yoksa otomatik olarak indirilir ve ayarlanır

Shebang ile doğrudan çalıştırılabilen betikler yazma

  • Shebang (#!...) kullanılarak uv run --script biçiminde doğrudan çalıştırılabilen dosyalar oluşturulabilir
  • Bu durumda da bağımlılık bildirimi ve Python sürümü gibi bilgiler betiğin üst kısmında belirtilebilir

Paket indeksi ve kimlik doğrulama desteği

  • --index seçeneğiyle özel paket indeksleri kullanılabilir
  • İndeks bilgileri de metadata içine dahil edilebilir
  • Kimlik doğrulama gerekiyorsa ilgili belgelere başvurulabilir

Bağımlılık kilitleme (Lock) ve yeniden üretilebilirliği artırma

  • uv lock --script ile betik bazında Lock dosyaları oluşturulup yönetilebilir
  • Daha sonra çalıştırma veya bağımlılık ekleme sırasında lock dosyası yeniden kullanılır ve gerektiğinde güncellenir
  • Sürüm yeniden üretilebilirliği için exclude-newer seçeneği sunulur; bu seçenek belirli bir tarihten sonraki sürümleri hariç tutar
  • Tarih, RFC 3339 zaman damgası ile belirtilir

Python sürümünde esneklik

  • Her çalıştırmada komut satırı seçeneğiyle istenen herhangi bir Python sürümünün kullanılması belirtilebilir
  • Örnek: uv run --python 3.10 example.py

Windows desteği

  • .pyw uzantılı betikler Windows'ta pythonw ile çalıştırılır
  • GUI tabanlı betikler de bağımlılıklarıyla birlikte çalıştırılabilir

Referans belgeler

  • Daha ayrıntılı komut kullanımı için CLI referans belgeleri ile aracın çalıştırma/kurulum kılavuzlarına başvurulabilir

Sonuç

  • uv, Python betiklerinin çalışma ortamını, bağımlılıklarını, sürümlerini, paket indekslerini ve yeniden üretilebilirliğini otomatik ve pratik şekilde yöneterek aynı anda hem üretkenliği hem de güvenilirliği artıran bir araçtır

İlgili okumalar

7 yorum

 
ihabis02 2025-07-24

Ben de pipten uvye geçtim; gerçekten sadece hızının çok yüksek olması bile geçmeye değer bir seviye gibi geldi bana.
 
idunno 2025-07-23

Sık sık gündeme geliyordu, ben de dün ilk kez denedim.. gerçekten çok hızlıymış. Vay canına..
 
ytuniverse 2025-07-23

Sanırım burada uv ile ilgili 5'ten fazla gönderi gördüm;;;
 
pmc7777 2025-07-23

Diğer özellikleri bir kenara bıraksak bile, sırf hızı için bile kullanmak için yeterli bir neden var.
Bana tekrar pip kullan deseler artık asla yapamam.

conda’nın sistem paketi yönetimini flake.nix ile değiştirip kullanıyorum; ortak çalışma gerektiren ya da mevcutta conda+pip ile bakımı yapılan projeler dışında, kişisel olarak bundan sonra uv+nix kullanacak gibi görünüyorum.
 
ndrgrd 2025-07-22

Son zamanlarda çoğu Python çalıştırmasını uv ile değiştirdim ve gerçekten çok hızlı.
Birkaç gelişmiş özellik tam uyumlu olmasa da, çoğu durumda neredeyse aynı şekilde çalışıyor.
 
GN⁺ 2025-07-22
Hacker News yorumu

  • “Betik bağımlılıklarını bildirme” özelliğinin gerçekten çok kullanışlı olduğunu deneyimledim
    Resmî kılavuzda anlatıldığı gibi, Python kodunun en üstüne yorum olarak bağımlılıkları şu şekilde yazabiliyorsunuz

    # /// script
# dependencies = [
#  "requests<3",
#  "rich",
# ]
# ///
import requests, rich
# ... script

    Bu dosyayı script.py olarak kaydedip ardından uv run script.py ile çalıştırırsanız, belirtilen bağımlılıklar sihirli bir şekilde geçici bir sanal ortama kuruluyor ve betik hemen çalışabiliyor
    Bu, Python’un PEP 723 standardının bir uygulaması ve Claude 4 de bu numarayı bildiği için “satır içi betik bağımlılıkları içeren bir Python betiği” yazmasını isterseniz bunu doğru şekilde oluşturuyor
    Örneğin httpx ve click kullanarak büyük bir dosyayı indirip ilerleme çubuğu gösteren bir kod yazmasını isteyebilirsiniz
    Claude 4’ten önce bu tür bir işlev için özel bir proje ve ayrıca yönlendirme gerekiyordu, ama artık gerekmiyor
    Ayrıntılı kullanım örneklerine de bakabilirsiniz

    • shebang modu da gerçekten çok kullanışlı
      Aşağıdaki gibi betiğin ilk satırına shebang eklerseniz ./script.sh gibi çalıştırabilirsiniz

      #!/usr/bin/env -S uv run --script
# /// script
# dependencies = [
#  "requests<3",
#  "rich",
# ]
# ///
import requests, rich
# ... script

    • Keşke requirements dosyasıyla aynı biçimde olsaydı
      Öyle olsaydı, uv kullanmayanlar için basit bir yorum satırıyla aynı şeyi pip üzerinden kurabilecekleri tek satırlık bir komut da verilebilirdi
      Örneğin pip install -r <(head myscript.py) gibi bir yaklaşım mümkün olabilirdi

    • Aslında PEP723 bugünlerde dikkat çeken uv dışında pipx ve hatch tarafından da destekleniyor
      Ayrıca pip-tools gibi araçlar da destek yol haritasında yer alıyor
      (ilgili issue)

    • İlk gördüğümde requests yanındaki şeyi kalp emojisi sanmıştım

    • Bunun gerçekten harika bir yaklaşım olduğunu düşünüyorum
      Ama bir gün sihirli yorumlar yerine yerleşik dil sözdizimi olarak benimsenmesini isterdim
      Yorumlar biraz dağınık görünüyor
      Elbette araçlar açısından sihirli yorumların ayrıştırılması daha kolay ve Python çekirdeğinin paketleme bilgisi konusunda sınırlı olması gibi yapısal meseleler olduğunu biliyorum, ama yine de bir gün yerleşik sözdizimi olmasını isterim

  • Bu yaklaşıma katılıyorum
    Python’da requirements.txt zorunlu değil ama bakım ihmal edilirse işlerin bozulması çok kolay; bu can sıkıcı
    ilgili tweet

  • Bu yaklaşımda karşılaştığım bir tuzağı paylaşmak istiyorum
    İnternet kesildiğinde yönlendiriciyi yeniden başlatan bir betikte bunu kullanmıştım, fakat bağımlılık kurulum davranışı internet bağlantısına bağlı olduğu için ağ yoksa betiğin kendisi de çalışamaz hâle geliyor
    Neyse ki bunu önceden fark edip bağımlılıkları önceden kurarak çözdüm, ama benim yaptığım hatayı yapmayın; gerçekten air-gapped bir ortamda (ağın tamamen izole olduğu bir ortamda) bunu kullanmamanızı öneririm
    uv önbelleği olsa bile cache miss yaşanabilir

    • uv run --offline seçeneğiyle önbelleğe alınmış bağımlılıkları kullanıp yeni sürüm kontrolü yapmadan çalıştırabilirsiniz
      Aynı şey uvx için de geçerli (uvx --offline ...)

    • Anladığım kadarıyla bağımlılıkları veya venv’yi kullanacaksanız, sonrasında çevrimdışı da kullanabilmek için en az bir kez internet bağlantısıyla çalıştırmanız gerekiyor

  • Son zamanlarda Python ekosistemindeki çeşitli özelliklerin giderek daha uyumlu çalıştığını hissediyorum
    Marimo ile uv betik bağımlılıklarını birleştirerek başka ekiplerin kullanması için uygun, yeniden üretilebilir raporlama/tanı aracı oluşturmaya başladım

  • uv içindeki en sevdiğim özellik bu oldu; hatta bu yüzden uv’ye geçtim
    Birden fazla git hook betiğinin her birinin ayrı bağımlılıkları vardı ve bunları ana venv içine kurmak istemiyordum
    Sadece #!/usr/bin/env -S uv run --script --python 3.13 satırını ekledim; geliştiricilere de yalnızca brew install uv demek yetti, ayrıca venv oluşturmaya gerek kalmadan doğrudan betiğin içinde kullanabildiler

    • -S bayrağının neden gerekli olduğunu bilen var mı diye merak ediyorum
      Benim BSD ortamımda /usr/bin/env -S uv run --python 3.11 python ile /usr/bin/env uv run --python 3.11 python ikisi de Python kabuğunu açıyor gibi görünüyor, yani sonuç aynı
      env kılavuzuna baktım ama net bir açıklama göremedim; faydalı bir bilgi varsa duymak isterim
      (Buradaki -S, argümanları boşluklara göre bölme işini yapıyor)

    • UV sayesinde aslında Python’daki büyük bir taşıma işini golang ile yapmayı planlıyordum, ama UV sayesinde bu taşımanın kapsamını küçültebildim
      Özellikle küçük betik tarzı işler için artık taşıma yapmaya gerek kalmadı

    • Bunun gerçek bir “killer feature” olduğuna eminim

  • Bağımlılıklar arasında Pytorch varsa bu yaklaşım biraz sınırlı kalabiliyor
    uv, Pytorch için entegre desteği gayet iyi sunuyor, ancak yalnızca betik başlığıyla en uygun wheel indeksini (CPU, CUDA, ROCm vb.) açıkça seçmenin bir yolu olmaması üzücü

  • Keşke VS Code, uv’nin otomatik oluşturduğu venv’yi kolayca tanıyabilse
    Şu an Python eklentisi tüm üçüncü taraf import ifadelerinin altını kırmızı çiziyor
    Geçici çözüm olarak uv önbellek dizininden venv yolunu elle bulup kaydediyorum, ama venv sık sık yeniden oluşturulunca bunu tekrar tekrar yapmak gerekiyor

    • uv python find --script "${filePath}" komutuyla ortam yolunu bulabilirsiniz
      Bunu VS Code içinde otomatik algılayıp etkinleştiren bir eklenti geliştiriyorum

  • UV’nin bu özelliğini gerçekten çok seviyorum
    jupyter notebook bile ayrı kurulum gerektirmeden şu tek satırla çalıştırılabiliyor

    uv run --with jupyter jupyter notebook

    Her şey geçici bir sanal ortama kuruluyor ve sonrasında temizleniyor
    Bir proje içinde çalıştırılırsa o projenin bağımlılıklarını da otomatik olarak algılıyor

    • Yine de tamamen “temiz” sayılmaz; uv önbellek klasörü zamanla büyümeye devam edebilir

    • Ben de uv run --with ipython --with boto3 ipython gibi komutları sık kullanıyorum ve gerçekten çok zaman kazandırıyor

  • Yakın zamanda uv run ile ilgili küçük bir sorun keşfettim
    Betiği proje klasörünün dışından çalıştırırsanız, gerçek betik dosyasının konumu yerine mevcut çalışma dizininde pyproject.toml arıyor
    Bu yüzden bağımlılıklarını pyproject.toml içinde tutan bir betik, dışarıdan uv run path/to/my/script.py şeklinde çalıştırıldığında düzgün çalışmayabiliyor
    Bu durum her zaman satır içi bağımlılık kullanarak ya da --project argümanını vererek çözülebiliyor, ama betik yolunu iki kez yazmak gerektiği için kullanışsız
    uv genel olarak çok iyi, ama bu küçük davranış oldukça can sıkıcı gelebiliyor

  • uv’ye özel shebang ve betik içi bağımlılık yaklaşımını memnuniyetle kullanıyordum
    Buna ek olarak uv lock --script example.py komutuyla tek bir betiğe özel lock dosyası da üretilebilmesi beni daha da etkiledi
    Python paketleme ekosistemi 20 yılı aşkın süredir var ve ancak şimdi bu kadar doğal bir deneyimin ortaya çıkmış olması şaşırtıcı

    • Tek betik için lock üretmenin kullanım senaryolarını merak ediyorum
      Bizim organizasyonda lockfile bağımlılıklarını trivy fs uv.lock gibi araçlarla tarıyoruz; böylece bilinen CVE’lere sahip kodların çalıştırılmasını önlemeye de yardımcı oluyor