Kalau kamu pernah mengelola project Python, kamu pasti akrab dengan ritual yang melelahkan ini: membuat venv, mengaktifkannya, menjalankan pip install satu per satu, lalu menunggu lama setiap kali ada dependensi yang berubah. Prosesnya lambat, rawan error, dan membuat frustrasi saat harus diulang di banyak project sekaligus.

uv hadir untuk menyelesaikan masalah itu. uv adalah package manager sekaligus project manager untuk Python yang ditulis dengan Rust oleh tim Astral (pembuat linter Ruff). Ia bisa menggantikan pip, venv, pyenv, poetry, dan pipx sekaligus — dengan kecepatan 10–100x lebih cepat berkat caching agresif dan resolusi dependensi yang modern. Tidak heran uv menjadi salah satu tool paling hype di ekosistem Python dalam beberapa tahun terakhir.

Apa Itu uv dan Kenapa Ia Begitu Cepat?

Secara sederhana, uv adalah satu binary yang mampu menangani hampir semua hal yang sebelumnya butuh banyak tool terpisah. Berikut peran yang bisa diambil alih uv:

  • Pengganti pip — menginstal dan mencopot paket dengan sangat cepat.
  • Pengganti venv/virtualenv — membuat environment terisolasi secara otomatis.
  • Pengganti pyenv — mengunduh dan mengelola banyak versi Python.
  • Pengganti poetry — mengelola pyproject.toml dan lock file dengan satu perintah.
  • Pengganti pipx — menjalankan tool CLI seperti ruff, black, dan cookiecutter tanpa menginstalnya permanen.

Kenapa bisa secepat itu? uv memakai resolver Rust yang berjalan paralel, cache global yang dibagikan antar-project, dan tidak pernah menduplikasi paket yang sama. Hasilnya, operasi yang tadinya butuh puluhan detik di pip bisa selesai dalam hitungan puluhan milidetik.

Prasyarat

Untuk mengikuti tutorial ini, kamu hanya butuh:

  • Terminal (Linux, macOS, atau WSL/PowerShell di Windows).
  • Koneksi internet untuk mengunduh uv dan paket Python.
  • Kamu tidak wajib sudah punya Python — uv bisa mengunduh versi Python yang dibutuhkan secara otomatis.

Semua perintah di artikel ini identik di Linux, macOS, dan Windows. Kalau kamu pakai Windows, jalankan lewat PowerShell atau Git Bash.

Langkah 1: Instalasi uv

Cara paling praktis adalah lewat installer resmi. Jalankan perintah ini di terminal:

bash
# Linux & macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

Alternatif instalasi lainnya:

  • Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • Via pip: pip install uv
  • Via Homebrew (macOS): brew install uv

Setelah selesai, buka ulang terminal (atau jalankan source ~/.bashrc atau source ~/.zshrc), lalu verifikasi instalasinya:

bash
uv --version
# uv 0.12.2

Kalau nomor versi muncul, uv sudah siap dipakai. Mari langsung buat project pertama.

Langkah 2: Membuat Project Baru dengan uv init

Workflow lama memaksamu membuat folder, menulis pyproject.toml manual, lalu membuat venv. Dengan uv, satu perintah sudah cukup:

bash
uv init belajar-uv
cd belajar-uv

uv akan membuat struktur project modern dengan layout src/:

other
belajar-uv/
├── .gitignore
├── .python-version
├── README.md
├── pyproject.toml
└── src/
    └── belajar_uv/
        └── __init__.py

Isi pyproject.toml yang dihasilkan kira-kira seperti ini (format TOML):

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

[project.scripts]
belajar-uv = "belajar_uv:main"

[build-system]
requires = ["uv_build>=0.12.2,<0.13.0"]
build-backend = "uv_build"

Perhatikan beberapa hal penting: uv otomatis mengisi nama penulis dari konfigurasi git kamu, mendeklarasikan entry point belajar-uv yang memanggil fungsi main() di dalam paket, serta menyiapkan build system modern berbasis uv_build. File .python-version menentukan versi Python yang dipakai project ini.

File __init__.py yang dibuat uv sudah berisi contoh fungsi main() yang mencetak Hello from belajar-uv!. Kamu bisa langsung menjalankannya dengan uv run belajar-uv.

Langkah 3: Menambahkan Dependensi dengan uv add

Daripada mengedit pyproject.toml manual lalu menjalankan pip install, gunakan uv add. Misalnya kita butuh requests untuk memanggil API:

bash
uv add requests

Output yang muncul kira-kira seperti ini — perhatikan betapa cepatnya prosesnya:

bash
Resolved 6 packages in 49ms
Installed 6 packages in 11ms
 + requests==2.34.2

uv add melakukan tiga hal sekaligus: (1) menambahkan baris requests>=2.34.2 ke bagian dependencies di pyproject.toml, (2) membuat/memperbarui file uv.lock yang mengunci versi pasti semua paket, dan (3) menginstal paket tersebut ke environment project. Sekarang pyproject.toml kamu berubah menjadi:

other
[project]
name = "belajar-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.34.2",
]

Jangan mengedit uv.lock secara manual. File ini dikelola otomatis oleh uv dan berisi versi persis beserta hash setiap paket, sehingga build bisa direproduksi secara konsisten di semua mesin.

Langkah 4: Menjalankan Kode dengan uv run

Salah satu fitur paling nyaman dari uv adalah uv run. Kamu tidak perlu mengaktifkan virtual environment secara manual — uv melakukannya diam-diam. Buat file app.py berikut:

python
# app.py
import requests

url = "https://api.github.com/repos/astral-sh/uv"
resp = requests.get(url, timeout=10)
data = resp.json()

print(f"Repo     : {data['full_name']}")
print(f"Bintang  : {data['stargazers_count']}")
print(f"Deskripsi: {data['description']}")

Jalankan dengan:

bash
uv run python app.py

uv akan memastikan environment punya semua dependensi, lalu menjalankan skrip. Contoh outputnya:

bash
Repo     : astral-sh/uv
Bintang  : 89060
Deskripsi: An extremely fast Python package and project manager, written in Rust.

uv run juga bisa menjalankan entry point yang sudah kamu deklarasikan, misalnya uv run belajar-uv. Kalau kamu memberi perintah yang bukan entry point, uv otomatis meneruskannya ke Python di dalam environment project.

Langkah 5: Mengunci Dependensi dengan uv lock dan uv sync

Untuk project yang dibagikan ke tim, kamu ingin semua orang memakai versi paket yang persis sama. File uv.lock menyimpan versi terkunci, lalu uv sync memastikan environment cocok dengan lock file:

bash
# Perbarui lock file secara eksplisit
uv lock

# Sinkronkan environment dengan lock file
uv sync

Untuk melihat pohon dependensi (termasuk dependensi transitif), gunakan uv tree:

bash
uv tree
# belajar-uv v0.1.0
# └── requests v2.34.2
#     ├── certifi v2026.7.22
#     ├── charset-normalizer v3.5.1
#     ├── idna v3.19
#     └── urllib3 v2.7.0

Dengan alur uv add → uv lock → uv sync, anggota tim cukup menjalankan uv sync setelah clone dan langsung mendapatkan environment yang identik.

Langkah 6: Mengelola Versi Python dengan uv python

Kamu tidak perlu lagi repot mengompilasi Python atau memakai pyenv. uv bisa mengunduh dan mengelola berbagai versi Python secara otomatis. Lihat versi yang tersedia:

bash
uv python list

Misalnya project membutuhkan Python 3.12. Tinggal jalankan:

bash
uv python install 3.12
uv python pin 3.12

uv python pin menulis versi tersebut ke file .python-version, sehingga siapa pun yang menjalankan uv run atau uv sync otomatis memakai Python 3.12 untuk project ini. Kalau versi itu belum terinstal, uv akan mengunduhnya sendiri.

uv menyimpan versi Python hasil unduhan di direktori cache miliknya sendiri (bukan di sistem), jadi tidak akan mengganggu Python bawaan OS kamu. Aman digunakan berdampingan dengan Python sistem.

Langkah 7: Menjalankan Tool Sekali Pakai dengan uvx

Pernah perlu menjalankan tool seperti ruff, black, atau cookiecutter hanya sesekali, tapi malas menginstalnya secara global? Gunakan uvx (padanan pipx):

bash
# Periksa versi ruff tanpa menginstalnya permanen
uvx ruff --version
# ruff 0.16.4

# Format kode dengan black
uvx black app.py

uvx mengunduh tool ke cache, menjalankannya, lalu membersihkannya. Ini cara paling higienis untuk memakai tool CLI tanpa mencemari environment global.

Langkah 8: Migrasi dari pip dan requirements.txt

Sudah punya project lama yang memakai requirements.txt? uv bisa membacanya tanpa perlu menulis ulang. Dua skenario umum:

bash
# 1) Instal isi requirements.txt ke environment project
uv pip install -r requirements.txt

# 2) Ubah requirements.txt menjadi daftar versi yang terkunci
uv pip compile requirements.txt -o requirements.lock.txt

Kalau kamu hanya butuh virtual environment biasa (misalnya untuk deploy), buat dengan satu perintah:

bash
uv venv
# Creating virtual environment at: .venv
# Activate with: source .venv/bin/activate

Untuk migrasi penuh ke alur modern, pindahkan isi requirements.txt satu per satu ke uv add, atau cukup mulai project baru dengan uv init dan uv add.

Hati-hati saat mencampur uv pip install dengan uv add di project yang sama. Idealnya pilih satu alur: pakai uv add/uv sync untuk project yang dikelola lewat pyproject.toml, atau uv pip untuk lingkungan ad-hoc.

Cheat Sheet: Perintah uv yang Wajib Kamu Hafal

bash
uv init <nama>           # buat project baru
uv add <paket>           # tambah dependensi + update lock
uv remove <paket>        # hapus dependensi
uv run <perintah>        # jalankan perintah di environment project
uv lock                  # perbarui lock file
uv sync                  # sinkronkan environment dengan lock
uv tree                  # lihat pohon dependensi
uv python install 3.12  # unduh versi Python tertentu
uv python pin 3.12       # tetapkan versi Python project
uvx <tool>               # jalankan tool CLI sekali pakai
uv venv                  # buat virtual environment manual

Simpan cheat sheet di atas sebagai referensi cepat. Sebagian besar workflow harian kamu cukup memakai tiga perintah: uv init, uv add, dan uv run.

Kesimpulan

uv merangkum tooling Python yang dulu tersebar menjadi satu binary yang cepat dan konsisten. Kamu sudah belajar menginstal uv, membuat project, menambah dan mengunci dependensi, menjalankan kode, mengelola versi Python, memakai uvx, hingga migrasi dari pip.

Kecepatannya yang luar biasa plus alur kerja yang rapi menjadikan uv pilihan terbaik untuk project Python baru — baik untuk proyek pribadi maupun tim. Kalau kamu serius dengan Python, mempelajari uv adalah investasi waktu yang sangat sepadan.

Langkah berikutnya yang disarankan: coba migrasi satu project lama kamu ke uv minggu ini, lalu bandingkan waktu install-nya dengan pip. Kemungkinan besar kamu tidak akan mau kembali lagi.