Dokumentasi uv

uv adalah satu tool yang menggantikan pip, virtualenv, pyenv, pip-tools, dan pipx sekaligus. Halaman ini merangkum peta besarnya.

Kenapa uv ada

Selama belasan tahun, Python tidak punya satu tool resmi untuk mengelola proyek. Yang ada adalah tumpukan tool yang masing-masing menyelesaikan satu potongan masalah, dan kamu harus menyatukannya sendiri:

uv mengambil kelima peran itu. Itulah alasan roadmap ini menyuruh kamu melewati semua tutorial yang masih mengajarkan python -m venv + pip install -r requirements.txt. Bukan karena cara lama itu salah, tapi karena kamu akan membuang waktu belajar tiga tool untuk satu hasil.

Model mentalnya: proyek, bukan environment

Ini pergeseran cara berpikir yang penting. Dengan pip, unit kerjanya adalah environment — kamu mengaktifkan sebuah venv, lalu perintah pip dan python menempel ke venv aktif itu. Kalau lupa mengaktifkan, package-nya masuk ke Python sistem.

Dengan uv, unit kerjanya adalah direktori proyek. Selama ada pyproject.toml di folder itu, uv tahu venv mana yang dipakai dan membuatnya otomatis kalau belum ada. Tidak ada state tersembunyi berupa "shell mana yang lagi aktif".

# Cara lama — tiga langkah, satu di antaranya gampang lupa
python -m venv .venv
source .venv/bin/activate      # ← lupa ini = package nyasar
pip install httpx

# Cara uv — satu langkah, tanpa state
uv add httpx

Anatomi sebuah proyek uv

proyek-pertama/
├── pyproject.toml     # deklarasi: nama proyek, versi Python, daftar dependency
├── uv.lock            # hasil resolusi: versi persis tiap package + hash-nya
├── .venv/             # dibuat & dikelola uv, jangan di-commit
├── .python-version    # versi interpreter untuk proyek ini
└── main.py

Dua file yang penting kamu bedakan:

• pyproject.toml — apa yang kamu minta. Ditulis manusia (atau lewat uv add). Isinya longgar: httpx>=0.27. Di-commit ke git.
• uv.lock — apa yang benar-benar dipakai. Ditulis uv. Isinya persis: httpx==0.28.1 plus semua dependency turunannya. Di-commit juga — inilah yang membuat kodemu jalan sama persis di laptop orang lain.

Alur kerja harian

uv init proyek-baru        # bikin pyproject.toml + struktur dasar
cd proyek-baru

uv add anthropic httpx     # tambah dependency (venv dibuat otomatis kalau perlu)
uv add --dev pytest ruff   # dependency yang cuma dipakai saat ngoding
uv remove httpx            # hapus

uv run main.py             # jalankan script
uv run pytest              # jalankan tool dari dependency proyek
uvx ruff check             # jalankan tool SEKALI TANPA menambahkannya ke proyek

uv sync                    # samakan .venv dengan uv.lock (dipakai di CI & setelah git pull)
uv lock --upgrade          # naikkan versi dalam batas yang diizinkan pyproject.toml

uv run vs uvx

Dua perintah ini sering tertukar. Bedanya sederhana:

Mengelola versi Python

uv juga memasang interpreter Python-nya sendiri — kamu tidak perlu menyentuh Python bawaan sistem operasi (yang di Linux sering dipakai OS dan berbahaya kalau diutak-atik).

uv python install 3.13     # pasang interpreter
uv python list             # lihat yang tersedia & terpasang
uv python pin 3.13         # kunci versi untuk proyek ini (bikin .python-version)

Peta dokumentasi resmi

Dokumentasi uv luas. Urutan baca yang efisien untuk roadmap ini:

1. Getting started → Installation & First steps — 10 menit, wajib.
2. Guides → Working on projects — inti dari cara kerja harian. Ini yang paling penting.
3. Guides → Using tools — memahami uvx dan tool sekali pakai.
4. Guides → Integration → Docker — nanti saja, saat Fase 6.
5. Concepts, Reference, Workspaces — lewati. Buka hanya saat butuh.

Kesalahan yang sering terjadi