Tutorial Migrasi dari Pip ke uv: Python Package Manager Modern dari Astral

Pengelolaan dependensi di Python telah lama menjadi topik yang memicu perdebatan di kalangan developer. Pip yang tersebar luas seringkali lambat, tidak memiliki native lockfile, dan memerlukan kombinasi dengan virtualenv serta pip-tools untuk workflow yang deterministik. Masukkan uv, package manager baru dari Astral yang menggabungkan installer, resolver, virtual environment manager, dan lockfile generator dalam satu binary. Artikel ini adalah panduan praktis untuk memigrasikan project Python yang sudah berjalan dari pip ke uv, langkah demi langkah, tanpa mengorbankan productivity tim.

Dibangun dengan Rust, uv menjanjikan kecepatan yang jauh melampaui pip dan conda. Benchmark internal Astral menunjukkan uv bisa menginstal dependency sekitar 10-100 kali lebih cepat dibandingkan pip pada environment yang kompleks. Kecepatan ini bukan gimmick: ia mengubah cara developer bekerja karena menunggu resolving dependency tidak lagi menjadi bottleneck saat switch branch atau setup environment baru di CI/CD.

Persiapan Sebelum Migrasi

Sebelum menyentuh command line, audit dulu kondisi project saat ini. Buat daftar file yang perlu kamu perhatikan:

• requirements.txt atau requirements/ folder dengan file terpisah untuk dev, test, dan production.

• setup.py, setup.cfg, atau pyproject.toml yang sudah ada.

• Virtual environment yang sedang aktif beserta lokasinya.

• Script CI/CD yang memanggil pip secara eksplisit.

Pastikan repository berada di branch terpisah untuk migrasi ini. Commit semua perubahan yang belum disimpan. Sebaiknya juga lakukan backup dari requirements.txt yang sudah terkunci melalui pip freeze agar bisa rollback jika terjadi masalah dependency resolution.

Langkah 1: Instal uv di Sistem

Astral menyediakan installer universal yang bekerja di Linux, macOS, dan Windows. Jalankan perintah berikut:

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

Script tersebut akan menempatkan binary uv di ~/.cargo/bin/uv. Verifikasi dengan uv --version. Untuk update ke versi lebih baru, jalankan uv self update.

Perlu diperhatikan bahwa uv tidak bergantung pada Python interpreter yang sudah terinstall. Ia bahkan bisa menginstal Python sendiri melalui uv python install, sebuah fitur yang sangat berguna untuk environment bersih.

Langkah 2: Inisialisasi Project dengan uv

Masuk ke root directory project Python-mu dan jalankan:

uv init

Perintah ini akan membuat atau memperbarui pyproject.toml dengan metadata project dasar. Perbedaan fundamental dari pip: uv memanfaatkan pyproject.toml untuk declarative dependency dan menghasilkan uv.lock sebagai lockfile deterministik. File lock ini mencatat setiap transitive dependency beserta hash-nya, memastikan environment development identik persis dengan environment production.

Langkah 3: Migrasi Dependency dari requirements.txt

Perintah paling membantu dalam proses migrasi adalah:

uv add -r requirements.txt

uv akan membaca setiap baris dari requirements.txt, menambahkannya ke pyproject.toml, menjalankan dependency resolution, lalu menghasilkan uv.lock. Proses ini biasanya selesai dalam hitungan detik bahkan untuk project dengan ratusan dependency.

Jika project-mu memiliki multiple requirement files seperti requirements-dev.txt, gunakan:

uv add -r requirements.txt
uv add --dev -r requirements-dev.txt

Flag --dev menandakan dependency tersebut hanya dibutuhkan untuk development dan testing. uv akan memisahkan group ini dalam lockfile tanpa membuat file tambahan yang terpisah.

Langkah 4: Setup Virtual Environment dan Sync

uv membuat dan mengelola virtual environment secara otomatis. Jalankan:

uv venv
uv sync

Subcommand uv venv akan membuat .venv di root project dengan Python interpreter default. Kamu bisa menentukan versi Python tertentu dengan uv venv --python 3.12. Subcommand uv sync membaca uv.lock dan menginstal dependency dengan kecepatan tinggi melalui parallel downloading dan caching.

Cache uv adalah global dan shared antar project. Jika dependency sudah pernah diunduh untuk project lain, uv tidak akan mengunduh ulang.

Langkah 5: Jalankan Aplikasi dan Uji Coba

Untuk menjalankan script Python dalam environment yang sudah tersinkronisasi:

uv run python main.py

Command uv run secara otomatis mengaktifkan virtual environment tanpa perlu source .venv/bin/activate secara manual. Ia juga bisa mengeksekusi arbitrary command seperti uv run pytest atau uv run flask --app app run.

Pastikan semua test suite lulus setelah migrasi. Cek juga apakah ada import yang ternyata implicit dependency sebelumnya. Solusinya adalah menambahkan package secara eksplisit ke pyproject.toml dengan uv add.

Integrasi dengan CI/CD

Salah satu keuntungan terbesar uv adalah kecepatan resolving dan instalasi di pipeline CI. Ganti step pip install -r requirements.txt dengan:

pip install uv
uv sync

Karena uv memanfaatkan lockfile, kamu tidak perlu lagi menjalankan resolver di CI. Ini mengurangi waktu build pipeline secara signifikan, terutama untuk project dengan dependency tree yang lebar.

Untuk Docker, contoh Dockerfile minimal:

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:0.4 /uv /usr/local/bin/uv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY . .
CMD [uv, run, python, main.py]

Selain kecepatan, uv juga mengurangi friction saat developer baru bergabung ke tim. File uv.lock dan pyproject.toml memberikan single source of truth yang tidak perlu lagi dijelaskan secara verbal. Developer baru cukup menjalankan uv sync dan langsung mendapatkan environment yang identik dengan tim, tanpa perlu bertanya versi Python atau dependency mana yang perlu diinstall secara terpisah.

Kesimpulan

Migrasi dari pip ke uv bukan sekadar ganti tool: ia adalah pergeseran paradigma dalam cara mengelola environment Python. Dengan lockfile deterministik, kecepatan resolving yang order of magnitude lebih cepat, dan integrasi virtual environment yang seamless, uv menawarkan workflow yang modern dan scalable untuk tim kecil maupun besar.

Bagi developer Indonesia yang sedang membangun startup atau mengelola codebase internal, investasi waktu untuk migrasi ini akan kembali berlipat ganda dalam bentuk waktu yang dihemat setiap kali developer baru onboarding atau CI pipeline berjalan. Mulai dari project kecil hari ini, dan rasakan perbedaanya saat dependency tree project-mu tumbuh di masa depan.

Sumber referensi: Dokumentasi Resmi uv, Repository GitHub uv