Tutorial Migrasi dari pip ke uv: Manajemen Dependensi Python Modern

Python ecosystem akhir-akhir ini diguncang oleh hadirnya uv, package manager dan resolver dependensi yang ditulis dalam Rust oleh Astral. Tool ini mengklaim kecepatan 10 hingga 100 kali lebih cepat daripada pip dan virtualenv, serta mendukung lockfile, workspace, dan Python version management dalam satu binary. Banyak tim engineering di startup Indonesia mulai bermigrasi dari pip ke uv untuk mengurangi waktu CI/CD dan meningkatkan developer experience.

Artikel ini adalah panduan praktis untuk migrasi proyek Python yang sudah berjalan dari pip ke uv. Kita akan mulai dari instalasi, mengkonversi requirements.txt, membuat virtual environment, hingga menjalankan test suite. Semua langkah bisa diikuti dalam waktu kurang dari satu jam untuk proyek menengah.

Prasyarat dan Instalasi uv

uv didesain untuk bekerja di semua platform utama: Linux, macOS, dan Windows. Instalasi paling mudah dilakukan via official install script. Pastikan kamu memiliki curl dan shell yang umum seperti bash atau zsh.

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

Setelah instalasi selesai, restart terminal atau source file konfigurasi shell. Verifikasi instalasi dengan perintah:

uv --version

Output yang diharapkan adalah versi terbaru, misalnya uv 0.6.0. Jika terdapat error command not found, tambahkan ~/.cargo/bin ke PATH environment variable. Untuk Windows, gunakan PowerShell install script yang tersedia di dokumentasi resmi Astral.

Langkah 1: Inisialisasi Proyek dengan uv

Masuk ke direktori proyek Python yang ingin dimigrasi. Jika belum ada file pyproject.toml, jalankan perintah init untuk membuat struktur standar:

cd /path/to/your/project \nuv init

Perintah ini akan membuat pyproject.toml dengan build system default. Jika proyek kamu sudah memiliki pyproject.toml, uv akan membaca konfigurasi yang ada dan menambahkan section [tool.uv] jika diperlukan. Periksa file tersebut untuk memastikan tidak ada konflik dengan build system yang sebelumnya dipakai.

Untuk proyek yang masih menggunakan setup.py, uv tetap kompatibel. Namun, direkomendasikan untuk secara bertahap mengkonversi ke pyproject.toml agar bisa memanfaatkan fitur workspace dan lockfile secara penuh.

Langkah 2: Mengkonversi requirements.txt ke uv

Banyak proyek Python lama yang menggunakan requirements.txt sebagai sumber dependensi. uv bisa membaca file ini secara langsung, namun cara paling baik adalah mengkonversinya ke format lockfile yang native. Jalankan perintah berikut:

uv pip compile requirements.txt -o requirements.lock \nuv pip sync requirements.lock

Perintah compile akan melakukan dependency resolution secara deterministik, mirip dengan pip-tools. Hasilnya adalah requirements.lock yang berisi versi spesifik setiap paket beserta hash-nya. Perintah sync akan menginstall paket yang tercantum di lockfile ke virtual environment yang dikelola oleh uv.

Jika proyek menggunakan requirements-dev.txt terpisah, gunakan pendekatan multi-file:

uv pip compile requirements.in requirements-dev.in -o requirements.lock

File .in adalah file input yang hanya berisi nama paket tanpa versi, mirip konvensi pip-tools. Ini membuat manajemen dependensi lebih bersih dan lebih mudah di-review.

Langkah 3: Membuat dan Mengelola Virtual Environment

uv memiliki virtual environment manager yang terintegrasi. Berbeda dengan python -m venv, uv secara otomatis menggunakan Python interpreter yang sesuai dan menginstall dependensi dalam satu aliran perintah. Buat virtual environment baru:

uv venv --python 3.12

Perintah ini akan membuat direktori .venv dengan Python 3.12. Jika interpreter belum terinstall, uv akan otomatis mendownloadnya. Kemudian, aktifkan environment sesuai platform:

source .venv/bin/activate  # Linux/macOS \n.venv\Scriptsctivate    # Windows

Install semua dependensi dari lockfile dengan:

uv pip sync requirements.lock

Keunggulan uv: proses ini jauh lebih cepat karena uv menggunakan parallel fetching dan caching yang agresif. Cache disimpan di direktori global, sehingga proyek lain yang menggunakan paket yang sama tidak perlu mendownload ulang.

Langkah 4: Menjalankan Script dan Test Suite

Setelah dependensi terinstall, jalankan aplikasi atau test suite seperti biasa. uv menyediakan command wrapper uv run yang otomatis mengaktifkan virtual environment dan menjalankan command di dalamnya. Ini menghilangkan kebutuhan untuk mengaktifkan venv secara manual setiap kali membuka terminal baru.

uv run pytest tests/ -v \nuv run python main.py

Untuk CI/CD pipeline, gunakan perintah berikut agar instalasi bersih dan reproducible:

uv pip sync requirements.lock --no-cache

Flag --no-cache memastikan environment tidak terkontaminasi oleh cache lokal. Pipeline seperti GitHub Actions akan berjalan lebih cepat karena uv menggunakan minimal I/O dan tidak membuat temporary file yang berlebihan seperti pip.

Langkah 5: Fitur Lanjutan: Workspace dan Python Version Management

uv bukan sekadar pip replacement. Tool ini mendukung workspace, fitur yang memungkinkan monorepo dengan multiple Python packages. Inisialisasi workspace dengan membuat pyproject.toml di root dan menambahkan section workspace:

[tool.uv.workspace] \nmembers = [\packages/*\]

Setiap subdirektori di packages/ bisa memiliki pyproject.toml sendiri. uv akan mengelola lockfile tunggal untuk seluruh workspace, memastikan dependensi antar package tidak conflict. Fitur ini sangat berguna untuk startup yang memiliki shared library dan multiple microservices dalam satu repository.

Selain itu, uv bisa mengelola multiple Python version secara paralel. Gunakan perintah:

uv python install 3.11 3.12 3.13 \nuv run --python 3.12 python main.py

Dengan fitur ini, kamu tidak perlu lagi bergantung pada pyenv atau asdf. Semua manajemen versi Python berada dalam satu toolchain yang terintegrasi penuh.

Langkah 6: Troubleshooting dan Best Practices

Selama migrasi, beberapa masalah umum sering muncul. Yang pertama adalah conflict antara lockfile lama dan cache uv. Jika uv pip sync menghasilkan error dependency resolution, coba hapus cache dan lockfile lalu regenerate:

uv cache clean \nuv pip compile requirements.in -o requirements.lock \nuv pip sync requirements.lock

Masalah kedua adalah platform-specific dependency. Beberapa paket Python memiliki wheel hanya untuk Windows atau Linux. uv akan otomatis memilih wheel yang sesuai, namun jika paket hanya menyediakan source distribution, pastikan build tools seperti gcc atau rust terinstall di sistem. Gunakan flag --no-build-isolation hanya jika benar-benar diperlukan, karena mode default lebih aman.

Best practices untuk menggunakan uv di team: selalu commit uv.lock ke repository, jangan commit .venv. Gunakan uv run di README sebagai standard command untuk menjalankan aplikasi. Di CI/CD, gunakan uv pip sync dengan --frozen untuk memastikan lockfile tidak dimodifikasi secara tak terduga. Pola ini menjaga determinisme build dan mengurangi bug yang disebabkan oleh perbedaan versi dependensi antar environment.

Kesimpulan

Migrasi dari pip ke uv adalah upgrade yang worth it untuk proyek Python apapun. Kecepatan instalasi, determinisme lockfile, dan integrasi workspace menjadikan uv pilihan utama untuk engineering team modern. Proses migrasi yang dijelaskan di atas bisa dilakukan secara bertahap tanpa mengganggu production.

Langkah selanjutnya: pelajari fitur uv publish untuk publishing ke PyPI, dan eksplorasi uv tool untuk menginstall CLI packages secara global. Dokumentasi lengkap tersedia di docs.astral.sh/uv. Repository open source uv ada di GitHub astral-sh/uv.

Gambar: GitHub astral-sh/uv