uv — Working on projects

Halaman paling penting dari dokumentasi uv: bagaimana sebuah proyek Python modern dibentuk dan dijalankan sehari-hari.

Membuat proyek

uv init proyek-saya
cd proyek-saya

uv init membuat kerangka minimal:

proyek-saya/
├── .python-version    # versi Python untuk proyek ini
├── README.md
├── main.py
└── pyproject.toml

Untuk proyek yang akan dipaketkan (punya src/), pakai flag --package:

uv init --package proyek-saya   # menghasilkan struktur src/proyek_saya/

Membaca pyproject.toml

[project]
name = "proyek-saya"
version = "0.1.0"
description = "Deskripsi singkat"
readme = "README.md"
requires-python = ">=3.13"        # batas bawah versi Python
dependencies = [                   # dependency runtime — ikut ke production
    "anthropic>=0.40",
    "httpx>=0.28",
]

[dependency-groups]
dev = [                            # hanya untuk ngoding — TIDAK ikut ke production
    "pytest>=8.0",
    "mypy>=1.14",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Tiga bagian yang perlu kamu pahami:

• requires-python — batas versi interpreter. Ini yang membuat uv menolak menyelesaikan dependency yang tidak kompatibel, jauh sebelum kodemu error saat runtime.
• dependencies — yang dibutuhkan aplikasi saat berjalan. Ditulis longgar (>=), bukan dipaku (==). Yang memaku itu tugas lockfile.
• [dependency-groups] — pemisahan ini penting. Image Docker production-mu tidak perlu memuat pytest.

Siklus harian

1. Menambah dan menghapus dependency

uv add anthropic                  # tambah ke [project.dependencies]
uv add --dev pytest ruff mypy     # tambah ke grup dev
uv add "httpx>=0.28,<0.29"        # dengan batas versi eksplisit
uv add git+https://github.com/user/repo   # langsung dari git
uv remove anthropic

Satu perintah uv add melakukan tiga hal sekaligus:

1. Menulis baris baru ke pyproject.toml
2. Menyelesaikan seluruh graf dependency dan memperbarui uv.lock
3. Menyinkronkan .venv supaya cocok dengan lockfile

2. Menjalankan kode

uv run main.py
uv run python -c "import anthropic; print(anthropic.__version__)"
uv run pytest
uv run uvicorn app:app --reload

3. Menyinkronkan manual

uv sync                  # samakan .venv dengan uv.lock
uv sync --frozen         # sama, tapi ERROR kalau lockfile tidak sinkron dengan pyproject.toml
uv sync --no-dev         # hanya dependency runtime — untuk image production
uv sync --all-groups     # semua grup dependency

--frozen adalah flag yang kamu pakai di CI dan Dockerfile. Tanpa itu, uv boleh menyelesaikan ulang dependency diam-diam — artinya build di CI bisa memakai versi berbeda dari yang kamu uji di laptop. Dengan --frozen, ketidakcocokan jadi error yang terlihat.

4. Menaikkan versi

uv lock --upgrade                # naikkan semua, dalam batas pyproject.toml
uv lock --upgrade-package httpx  # naikkan satu package saja
uv sync                          # terapkan ke .venv

Apa yang di-commit ke git

Menjalankan script satu file

Untuk script kecil yang butuh dependency tapi tidak layak jadi proyek penuh, uv mendukung metadata inline (PEP 723) — dependency ditulis di dalam file script itu sendiri:

uv add --script analisa.py httpx

# /// script
# requires-python = ">=3.13"
# dependencies = ["httpx"]
# ///

import httpx
print(httpx.get("https://example.com").status_code)

uv run analisa.py    # uv baca blok metadata, siapkan env sementara, jalankan

Sangat berguna untuk script utilitas — bisa dikirim ke orang lain sebagai satu file yang langsung jalan.

Ringkasan perintah