Python Geliştiricileri ve Yeni Başlayanlar İçin UV Rehberi:

İlk olarak Medium’da yayımlandı.

Bu yazıda UV’nin ne olduğunu, neden tercih edildiğini ve hangi kapsamda kullanılabileceğini ele alacağım. Yazımın başında paket ve bağımlılık yöneticisi nedir ne işe yarar ve mevcut paket yöneticilerinin kısa bir analizi yer almaktadır. Yazı, özellikle Python projelerinde bağımlılık yönetimi ve ortam kurulumunu hızlı ve güvenilir bir şekilde yapmak isteyen geliştiriciler için faydalı olacağına inanıyorum.

UV Nedir ve Nereden Çıktı?

uv, Astral tarafından geliştirilmiş bir tool chain olarak karşımıza çıkıyor. Sadece bir paket yöneticisi değil aynı zamanda ihtiyaç duyulan neredeyse tüm araçların içinde bulunduğu bir proje yöneticisi olarak tanımlayabiliriz. Aynı zamanda açık kaynaklı ve ücretsiz olarak yayımlanmıştır.

Bu yeni nesil tool chain, Python projelerinin bağımlılıklarını yönetmek, sanal ortam oluşturmak ve projeyi paketlemek gibi işlemleri hızlı ve deterministik bir şekilde yapmayı amaçlar.

Rust tabanlı olması, performans artışındaki temel faktör olarak yer almakta; Rust, modern bir sistem programlama dili olarak yüksek seviyeli dil konforunu düşük seviyeli kontrol ve performansla birleştirir. Bu sayede bağımlılık yönetimi ve proje işlemlerini çok daha hızlı ve verimli bir şekilde gerçekleştirebilmektedir.

Paket ve Bağımlılık Yöneticisi Nedir?

Paket ve bağımlılık yöneticileri, bir ekosistemdeki kütüphaneleri ve bağımlılıkları yüklemek, güncellemek, kaldırmak ve yönetmek için kullanılan araçlardır.

Python ekosisteminde bilinen paket ve bağımlılık yöneticileri şunlardır:

Pip

Python’un varsayılan paket yöneticisidir.
Temel işlevi paket yükleme ve yönetimidir.
Sanal ortam (venv) kurulumları manuel olarak yapılmalıdır.
Paket kaynağı olarak PyPI kullanır.
Doğrudan bir lock dosyası desteği yoktur; bunun yerine pip-tools gibi ek araçlarla sağlanabilir.
Çapraz platform desteği vardır, ancak bu PyPI kütüphanelerinin işletim sistemi bağımlılıklarını çözmez.
Performans olarak yavaş olabilir (bağımlılık çözümlemesi sınırlı).
Paketleri güncellerken sürüm çatışmalarını çözmek kullanıcıya kalır.
Proje paketleme (setup, publish) süreci için doğrudan bir araç sunmaz.

Conda

Hem Python hem de sistem kütüphanelerini yönetebilir.
conda env komutu ile sanallaştırma yapılabilir.
Paket kaynakları: PyPI, Conda Forge.
Paket tanımları için environment.yml kullanılır.
Tam deterministik ortam için conda-lock desteği vardır.
Çapraz platform desteği sunar.
Özellikle data science / ML dünyasında yaygın kullanılır çünkü NumPy, SciPy, TensorFlow gibi kütüphanelerin binary derlenmiş sürümlerini sağlar.
Python dışı bağımlılıkları (C, Fortran, R, CUDA vb.) da kolayca yönetebilir.
Ağır çalışır, indirmeler ve çözümler pip/uv’ye göre daha yavaştır.

Poetry

Modern bir bağımlılık yönetim aracıdır.
TOML dosyası üzerinden proje yapılandırmasını kolaylaştırır.
poetry.lock ile deterministik bağımlılık yönetimi sunar.
Kendiliğinden sanal ortam oluşturur.
Paketleme ve yayınlama (publish) süreçlerini entegre biçimde destekler.
Bağımlılık çözümlemesi deterministik ve güvenilirdir.
CLI üzerinden proje şablonlama, bağımlılık ekleme/çıkarma, paket yayınlama gibi işlevleri içerir.
Pip veya conda kadar yaygın değil, özellikle kurumsal tarafta adaptasyonu daha yeni.

Peki, neden UV gibi bir araca ihtiyaç duyuldu?

UV’nin Çözüm Getirdiği Sorunlar

Pip ve Poetry birçok projede yeterli olsa da büyük projelerde eksik ve yetersiz kalabiliyor; bu noktada uv, kendinden önceki paket ve bağımlılık yöneticilerinin iyi yönlerinin toplandığı ve üzerine eklemeler yapılmış tek araç felsefesini yansıtır bir biçimde karşımıza çıkıyor.

Hız: uv, Rust ile yazıldığı için Python ile yazılan paket ve bağımlılık yöneticilerine göre ciddi performans avantajı sağlar.
Deterministik bağımlılık: uv.lock dosyası sayesinde tüm ortamlar aynı paket sürümleriyle çalışır.
Sistem bağımsızlığı: Farklı işletim sistemlerinde yaşanan uyumsuzluk problemlerini, önceden derlenmiş (python-build-standalone) Python dağıtımlarını indirip kullanarak ciddi oranda azaltır.
Offline kurulum ve yeni proje bağımlılıkları: Cache sayesinde ağ bağlantısı olmadan paket kurulumu yapılabilir.

Tamamını dikkate alarak UV için tek cümlelik bir özet yaparsak şunu demeliyiz: “Hızlı, modern, çok amaçlı ve deterministik.”

Hız Farkı Nerede Görülüyor?

uv özellikle şu işlemlerde pip’e kıyasla benchmark verileri incelendiğinde arada ciddi farklar görülmekte; bu fark paket kurulumlarında cold start senaryolarda yaklaşık 1.5 kat daha hızlı iken cache yapısı ile çok daha hızlı olabiliyor.

Warm cache senaryolarında ise uv’nin kendi dökümantasyonunda sunduğu grafik üzerinden baktığımızda trio paketinin bağımlılıklarının kurulumu 4.63 sn iken uv üzerinde aynı süreç 0.06 sn sürmekte.

Trio paketinin bağımlılıklarının warm cache ile kurulumu üzerinden yapılmış benchmark (kaynak: uv)

Hız farkının görüldüğü noktalar:

Paket kurulum ve paketleme
Bağımlılıkların çözümlenmesi
Python ortamının hazırlanması
Docker ve CI ortamlarında multi-stage build ve cache optimizasyonları

Peki uv Bunu Nasıl Başarıyor?

Bunun cevabı, cache yapısı, lock dosyası ve bytecode ön derleme yaklaşımlarında gizlidir.

Paralel Kurulum: UV, bağımlılıkları paralel olarak çözümler ve indirir; bu da özellikle çok sayıda bağımlılık içeren projelerde hızı artırır.

Cache Yapısı: İndirilen tüm paketler ve çözümlenen bağımlılıklar saklanır. İlk kurulumda paket indirilir; sonraki kurulumlarda ise tekrar indirilmek yerine cache’den okunur. Ayrıca lock dosyası sayesinde, cache ile uyumlu olan paketler doğrudan kullanılır. Ek olarak birden fazla proje arasında cache’i paylaşabilir; böylece aynı paketi birden çok kez indirmek gerekmez.

Ağdan bağımsız hızlı kurulum
Genel hız artışı

Bytecode Ön Derleme: Normalde .py dosyaları ilk çalıştırıldığında bytecode’a (.pyc) dönüştürülür ve öyle çalışır. uv, isteğe bağlı olarak bu dönüşümü paket kurulumu (install) sırasında yapabilir; böylece çalışma anında tekrar derleme gerekmez. Bu davranış varsayılan olarak kapalıdır ve --compile-bytecode seçeneği ya da UV_COMPILE_BYTECODE=1 ortam değişkeni ile etkinleştirilir.

Startup süresinin kısalması
Büyük projelerde, onlarca .py dosyası nedeniyle yaşanan ilk açılış gecikmesinin ortadan kalkması

uv’nin Sağladığı Ek Kolaylıklar

İlk olarak, tek bir araçla birçok işlevi kazandırması öne çıkıyor. uv, kendisinden önceki paket ve bağımlılık yöneticilerinin iyi yönlerini bir araya getirip eksik kaldığı noktaları geliştiren bir araçtır. Diğer yandan, sistem veya pyenv bağımsız standalone sürümlerini kendisi kurması, projelerin farklı işletim sistemlerinde yaşadığı sürüm uyumsuzluklarını, bağımlılıkların platforma özel versiyonlarını ve ortam yönetim araçlarının eksikliğini ortadan kaldırmamıza olanak tanır. Ancak bu, uv’nin sistem Python ile çalışamayacağı anlamına gelmez; sistem Python hâlâ kullanılabilir.

Lock dosyası sayesinde “bende çalışıyor, sende çalışmıyor” sorunu da ortadan kalkar. Bellek tüketimi, Rust tabanlı olması sayesinde düşüktür. Genel kullanıcı yorumlarını incelediğimde, hata çözümlemesi konusunda uv’nin oldukça başarılı olduğu izlenimini edindim; bu, sonsuz stack trace’lerde boğulmaktan kurtulmak anlamına gelir. Ayrıca CLI kullanımı, diğer paket ve bağımlılık yöneticilerine kıyasla daha sade ve kullanışlıdır.

uv’nin Sınırları

Doğal olarak, uv konusunda da henüz tam olarak olgunlaşmamış alanlar ve bazı sınırlılıklar bulunmaktadır.

Eski projelerde yaşanan sorunlar: uv, bağımsız (standalone) Python sürümlerini indirip sunmaktadır ve bu da kullanılabilecek Python sürümlerinde bir kısıtlama getirmektedir. Sabit bir Python sürümüne ihtiyaç duyan eski ve büyük projelerde bu durum bir engel oluşturabilmektedir. uv, dışarıdan kurulmuş Python sürümleriyle de çalışabilmektedir; fakat bu noktada da uyum sorunları yaşanabilmektedir.

uv’nin kapladığı alan: uv, cache yapısı nedeniyle zamanla büyüyen bir disk alanı kullanmaktadır. Bu cache, CLI üzerinden kolaylıkla temizlenebilir; ancak bu durumda cache’in sağladığı bazı avantajlar kaybedilmiş olur. Doğrudan venv kullandığımız durumlarla karşılaştıracak olursak, uv’nin oluşturduğu cache’in bilgisayarımızda oluşan tüm sanal ortamların yanında görece daha az yer kapladığını ve daha derli toplu kaldığını söyleyebiliriz.

uv Kurulumu

İlk olarak mevcut işletim sistemine uv kurulumunu gerçekleştirmeliyiz.

Windows için kurulum: PowerShell üzerinden aşağıdaki betik ile kurulumu gerçekleştirebilirsiniz:

irm https://astral.sh/uv/install.ps1 | iex

Bunun dışında Winget ile de kurulum gerçekleştirilebilir:

winget install --id=astral-sh.uv -e

Chocolatey kullanıyorsanız:

choco install uv

Scoop kullanıyorsanız:

scoop install uv

macOS için kurulum:

brew install uv

Linux için kurulum: Dağıtıma bağlı olarak DNF ile kurulum gerçekleştirebilirsiniz.

Fedora:

sudo dnf install uv

Snap:

sudo snap install astral-uv

Ya da doğrudan Astral üzerinden kurulum gerçekleştirebilirsiniz:

curl -LsSf https://astral.sh/uv/install.sh | sh

Eğer sisteminiz curl kullanımına izin vermiyorsa wget kullanabilirsiniz:

wget -qO- https://astral.sh/uv/install.sh | sh

Temel CLI Komutları ile uv Kullanımı

İlk olarak uv ile proje oluşturmaya bakalım. İstediğimiz dizinde:

uv init <proje-adi>

komutunu kullanarak bir proje oluşturabiliriz.

Bu komutu girdikten sonra uv bize bir projede ihtiyaç duyulan temel bileşenleri oluşturur. Oluşan dosyaların tanımları:

.gitignore: Git’e hangi dosya veya klasörleri izlememesi gerektiğini söyleyen dosyadır. (Evet, uv ile proje başlattığımızda git ortamı hazır olarak geliyor.) Eğer projeyi git kullanmayacak şekilde başlatmak istiyorsanız: uv init --no-git
uv.lock: Lock dosyası, bir projenin bağımlılıklarını kesin sürümleriyle kaydeder. Yani, proje başka bir bilgisayara taşındığında veya başka bir geliştirici tarafından açıldığında, tam olarak aynı paket sürümleri yüklenir.
pyproject.toml: TOML, yapılandırma dosyalarını insan tarafından okunabilir ve yazılabilir şekilde tanımlamak için kullanılan bir formattır.

[project]
name = "project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [ ]

README.md: Bir proje hakkında bilgi veren .md uzantılı Markdown dosyasıdır.
main.py: Başlangıç için yerleştirilmiş bir .py dosyasıdır.
.python-version: Python sürümünün tutulduğu dosyadır.

Python sürümlerini yönetmek

uv yalnızca paketleri değil, Python sürümlerinin kendisini de yönetebilir. Böylece ayrıca pyenv gibi bir araca ihtiyaç kalmaz.

uv python install 3.12
uv python list

uv python install ile istediğiniz Python sürümünü indirip kurabilir, uv python list ile de sistemde mevcut ve kurulabilir sürümleri görebilirsiniz.

Projeye kütüphane eklemek ve kaldırmak:

uv add <kütüphane-adı>
uv remove <kütüphane-adı>

Build oluşturmak:

uv build

Projeyi başlatmak:

uv run <python_dosyası.py>

Araçları geçici olarak çalıştırmak (uvx): Bir aracı projeye kalıcı bağımlılık olarak eklemeden, tek seferlik çalıştırmak istediğinizde uvx (kısaltması uv tool run) devreye girer. pipx’in yaptığı işin uv karşılığıdır. Örneğin ortamınızı kirletmeden ruff çalıştırmak için:

uvx ruff check

uv, aracı geçici ve izole bir ortamda indirip çalıştırır; işiniz bittiğinde ortalıkta artık bir kalıntı kalmaz. Sık kullandığınız bir aracı sistem genelinde kalıcı olarak kurmak isterseniz uv tool install <araç-adı> komutunu kullanabilirsiniz.

pip uyumluluk arayüzü (uv pip): Halihazırda pip ile çalışan bir projeniz varsa ya da uv’nin proje yapısına henüz geçmek istemiyorsanız, uv’nin tanıdık pip komutlarını taklit eden bir arayüzü vardır:

uv pip install <kütüphane-adı>
uv pip freeze

Bu sayede mevcut alışkanlıklarınızı bozmadan, yalnızca uv’nin hız avantajından faydalanarak geçiş sürecini yumuşatabilirsiniz.

pyproject.toml ve uv.lock arası senkronizasyon: Aslında uv bu işlemi paket yüklemelerinde kendisi yapar, fakat bağımlılıklar manuel olarak eklendiğinde veya pyproject.toml değiştirildiğinde sync komutu ile lock dosyası güncellenir.

uv sync

Bu komut ile toml ve lock dosyaları senkronize olur.

Sonuç

Genel incelemeden de anlaşılacağı gibi, uv, artı yönleriyle ve ihtiyaç duyulan araçları içeriğinde barındırması ile son derece kullanışlı bir tool chain. Eğitim ve bireysel kullanım alanlarında hızla yaygınlaşabilir. İleri süreçte uv’nin IDE entegrasyonlarının daha da olgunlaşacağını düşünüyorum; şu anda da VS Code ve PyCharm gibi ortamlarda, oluşturulan venv’in tanıtılmasıyla sorunsuz kullanılabiliyor. Astral UV’yi açık kaynaklı tutmaya ve geliştirmeye devam ederse, daha yaygın kullanımını göreceğimizi düşünüyorum.