Uv: Menjalankan skrip dengan dependensi

 (docs.astral.sh)
14 poin oleh GN⁺ 2025-07-22 | 7 komentar | Bagikan ke WhatsApp
  • Dengan uv, manajemen dependensi saat menjalankan skrip Python diotomatisasi
  • Tanpa perlu mengelola virtual environment secara terpisah, lingkungan untuk tiap skrip dibuat dan dipelihara otomatis
  • Paket yang dibutuhkan dapat dideklarasikan dengan berbagai cara seperti inline metadata atau opsi baris perintah
  • Versi Python dan manajemen paket juga dapat dideklarasikan per skrip serta disesuaikan secara otomatis
  • Dengan file lock dan opsi pembatasan versi dependensi, reproduktibilitas dan kemudahan pemeliharaan meningkat

Gambaran umum

  • uv adalah alat yang secara otomatis mengelola dependensi paket yang dibutuhkan sebuah skrip Python saat dijalankan
  • Pengguna tidak perlu lagi secara manual membuat virtual environment atau memasang paket
  • Alat ini menyediakan berbagai opsi eksekusi, cara memanfaatkan inline metadata, beragam metode deklarasi dependensi, serta berbagai fitur kontrol

Lingkungan Python dan peran uv

  • Python memiliki lingkungan tersendiri untuk setiap instalasi
  • Secara umum, membuat dan mengelola virtual environment adalah praktik yang disarankan
  • uv mengelola virtual environment secara otomatis dan menangani dependensi dengan pendekatan deklaratif
  • Skrip sederhana dapat langsung dijalankan hanya dengan uv run example.py
  • Jika hanya memakai standard library, semuanya berjalan tanpa pengaturan tambahan

Meneruskan argumen dan cara input

  • Argumen baris perintah dapat diteruskan ke skrip
  • Kode skrip juga dapat diterima dan dijalankan langsung dari standard input, serta mendukung fitur here-document

Lingkungan proyek dan opsi --no-project

  • Jika skrip dijalankan di dalam folder proyek (misalnya yang memiliki pyproject.toml), dependensi proyek juga akan dipasang
  • Jika tidak diperlukan, lingkungan proyek dapat diabaikan dengan menempatkan flag --no-project sebelum nama skrip

Deklarasi dan pengelolaan dependensi skrip

  • Jika memerlukan paket eksternal, dependensi dapat ditentukan saat menjalankan skrip dengan opsi baris perintah --with
  • Batasan versi tertentu juga didukung, dan beberapa dependensi dapat ditambahkan dengan mengulangi opsi tersebut
  • Dependensi tambahan bisa disertakan di lingkungan proyek, dan jika tidak diinginkan dapat dikendalikan dengan --no-project

Inline Script Metadata (format PEP 723)

  • Python kini mendukung format standar untuk mendeklarasikan dependensi atau versi Python langsung di dalam skrip
  • Dengan uv init --script, skrip yang berisi inline metadata dapat dibuat dengan mudah
  • Dengan uv add --script, dependensi yang dibutuhkan skrip dapat ditambahkan dan dikelola dalam format TOML
  • Jika inline metadata tersedia, dependensi proyek akan diabaikan dan hanya dependensi skrip yang diterapkan

Deklarasi dan pengelolaan versi Python

  • Versi Python yang diinginkan dapat ditentukan di dalam skrip atau saat eksekusi
  • Jika versi yang ditentukan belum tersedia, versi tersebut akan diunduh dan dikonfigurasi secara otomatis

Menulis skrip yang bisa langsung dijalankan dengan shebang

  • Dengan shebang (#!...), file eksekusi dapat dibuat agar berjalan langsung menggunakan pendekatan uv run --script
  • Dalam kasus ini, deklarasi dependensi dan versi Python juga dapat dituliskan di bagian atas skrip

Dukungan indeks paket dan autentikasi

  • Opsi --index memungkinkan penggunaan indeks paket kustom
  • Informasi indeks juga dapat dimasukkan ke dalam metadata
  • Jika memerlukan autentikasi, dokumentasi terpisah dapat dijadikan rujukan

Mengunci dependensi (Lock) dan meningkatkan reproduktibilitas

  • Dengan uv lock --script, file lock tingkat skrip dapat dibuat dan dikelola
  • Setelah itu, saat menjalankan skrip atau menambahkan dependensi, file lock akan digunakan kembali dan diperbarui bila diperlukan
  • Tersedia opsi exclude-newer untuk reproduktibilitas versi, yaitu mengecualikan rilis setelah tanggal tertentu
  • Tanggal ditentukan dalam format timestamp RFC 3339

Fleksibilitas versi Python

  • Pada setiap eksekusi, versi Python apa pun dapat ditentukan melalui opsi baris perintah
  • Contoh: uv run --python 3.10 example.py

Dukungan Windows

  • Skrip dengan ekstensi .pyw dijalankan dengan pythonw di Windows
  • Skrip berbasis GUI juga dapat dijalankan bersama dependensinya

Dokumen referensi

  • Untuk penggunaan perintah yang lebih rinci, lihat dokumentasi referensi CLI serta panduan eksekusi/pemasangan alat

Kesimpulan

  • uv adalah alat yang secara otomatis dan praktis mengelola lingkungan eksekusi, dependensi, versi, indeks paket, serta reproduktibilitas skrip Python, sehingga meningkatkan produktivitas dan keandalan sekaligus

Bacaan terkait

7 komentar

 
ihabis02 2025-07-24

Saya juga sudah mencoba beralih dari pip ke uv, dan ternyata memang cukup layak pindah hanya karena satu hal: kecepatannya benar-benar kencang.
 
idunno 2025-07-23

Sering muncul jadi kemarin saya baru pertama kali mencobanya.. benar-benar cepat. Wah..
 
ytuniverse 2025-07-23

Sepertinya saya sudah melihat lebih dari 5 postingan terkait uv di sini;;;
 
pmc7777 2025-07-23

Mengesampingkan fitur lainnya, alasan untuk memakainya sudah cukup hanya dari segi kecepatan saja.
Kalau disuruh pakai pip lagi, rasanya saya benar-benar tidak akan sanggup.

Untuk pengelolaan paket sistem ala conda, saya menggantinya dengan flake.nix, dan selain proyek kolaboratif atau proyek lama yang dikelola dengan conda+pip, secara pribadi ke depannya saya rasa akan memakai uv+nix.
 
ndrgrd 2025-07-22

Saya baru-baru ini mengganti sebagian besar eksekusi Python dengan uv, dan itu benar-benar cepat.
Memang ada beberapa fitur lanjutan yang tidak sepenuhnya kompatibel, tetapi dalam kebanyakan kasus perilakunya hampir sama.
 
GN⁺ 2025-07-22
Opini Hacker News

  • Saya merasakan sendiri bahwa fitur "deklarasi dependensi skrip" benar-benar berguna
    Seperti yang diperkenalkan dalam panduan resmi, Anda bisa menuliskan dependensi sebagai komentar di bagian paling atas kode Python seperti berikut

    # /// script
# dependencies = [
#  "requests<3",
#  "rich",
# ]
# ///
import requests, rich
# ... script

    Setelah file ini disimpan sebagai script.py lalu dijalankan dengan uv run script.py, dependensi yang dinyatakan akan secara ajaib dipasang ke virtual environment sementara dan langsung bisa dijalankan
    Ini merupakan implementasi dari PEP 723 di Python, dan Claude 4 juga mengetahui trik ini, jadi jika Anda memintanya menulis “skrip Python dengan dependensi skrip inline”, hasilnya akan dibuat dengan benar
    Sebagai contoh, Anda bisa memintanya menulis kode yang menggunakan httpx dan click untuk mengunduh file besar sambil menampilkan progress bar
    Sebelum Claude 4, fitur seperti ini memerlukan proyek khusus dan petunjuk terpisah, tetapi sekarang tidak lagi
    Bisa juga merujuk ke contoh use case yang lebih rinci

    • Saya juga merasa mode shebang sangat berguna
      Jika menambahkan shebang di baris pertama skrip seperti di bawah, file bisa dijalankan seperti ./script.sh

      #!/usr/bin/env -S uv run --script
# /// script
# dependencies = [
#  "requests<3",
#  "rich",
# ]
# ///
import requests, rich
# ... script

    • Saya berharap formatnya bisa sama seperti file requirements
      Jika begitu, untuk pengguna yang tidak memiliki uv, kita juga bisa memberikan one-liner sederhana dalam komentar agar bisa memasang dependensi yang sama dengan pip
      Misalnya, pendekatan seperti pip install -r <(head myscript.py) tampaknya memungkinkan

    • Sebenarnya PEP723 kini didukung bukan hanya oleh uv yang sedang banyak dibicarakan, tetapi juga oleh pipx dan hatch
      Dan dukungan untuk pip-tools dan lainnya juga sudah masuk dalam roadmap
      (lihat issue terkait)

    • Saat pertama kali melihatnya, saya sempat mengira di samping requests ada emoji hati

    • Menurut saya pendekatan ini benar-benar keren
      Tetapi suatu hari nanti saya berharap ini diadopsi sebagai sintaks bahasa bawaan, bukan magic comment
      Komentar seperti ini terlihat agak berantakan
      Tentu saja saya paham bahwa dari sudut pandang tool, magic comment lebih mudah diparse, dan ada pertimbangan struktural seperti Python core tidak terlalu banyak memuat pengetahuan packaging, tetapi saya tetap berharap suatu saat ada sintaks bawaan

  • Saya setuju dengan pendekatan seperti ini
    Memang di Python file requirements.txt tidak wajib, tetapi cukup disayangkan karena jika pengelolaannya diabaikan, sering muncul ketidaknyamanan saat fungsinya rusak
    Lihat tweet terkait

  • Saya ingin berbagi jebakan yang saya alami dengan pendekatan ini
    Saya memakainya untuk skrip yang me-restart router saat internet putus, tetapi karena proses pemasangan dependensi bergantung pada koneksi internet, ketika jaringan benar-benar mati, skripnya sendiri jadi tidak bisa berjalan
    Saya sempat menemukannya lebih awal dan mengatasinya dengan pra-instal dependensi, tetapi agar tidak mengulangi kesalahan saya, saya sarankan jangan menggunakannya di lingkungan airgapped yang benar-benar terisolasi dari jaringan
    Meski ada cache uv, cache miss tetap bisa terjadi

    • Jika menggunakan opsi uv run --offline, dependensi yang sudah tercache bisa dipakai untuk menjalankan tanpa mengecek versi baru
      Hal yang sama juga berlaku untuk uvx (uvx --offline ...)

    • Pemahaman saya, jika ingin memakai dependensi atau venv, setidaknya harus pernah dijalankan sekali saat terhubung ke internet agar setelah itu bisa dipakai secara offline

  • Belakangan ini saya merasa beberapa fitur di ekosistem Python makin saling cocok dan bekerja bersama dengan baik
    Dengan kombinasi dependensi skrip Marimo dan uv, saya mulai membuat alat pelaporan/diagnostik yang reproducible dan mudah dipakai tim lain

  • Fitur uv inilah yang paling saya sukai dan menjadi alasan saya pindah ke uv
    Saya punya beberapa skrip git-hooks yang masing-masing memiliki dependensi tersendiri, dan saya tidak ingin memasangnya ke venv utama
    Cukup dengan menambahkan satu baris #!/usr/bin/env -S uv run --script --python 3.13, saya hanya perlu memberi tahu para developer untuk brew install uv, dan mereka bisa langsung memakai skrip itu tanpa perlu membuat venv terpisah

    • Adakah yang tahu kenapa flag -S diperlukan?
      Di lingkungan BSD saya, /usr/bin/env -S uv run --python 3.11 python dan /usr/bin/env uv run --python 3.11 python sama-sama menjalankan Python shell, jadi rasanya hasilnya sama
      Bahkan setelah melihat manual env pun saya belum mendapat penjelasan yang jelas, jadi jika ada info berguna saya ingin mendengarnya
      (-S di sini berfungsi memecah argumen berdasarkan spasi)

    • Berkat UV, migrasi besar-besaran pekerjaan Python yang awalnya ingin saya pindahkan ke golang jadi bisa diperkecil ruang lingkupnya
      Terutama pekerjaan kecil berbentuk skrip, kini tidak perlu dipindahkan lagi

    • Saya yakin fitur ini benar-benar "killer feature"

  • Jika ada Pytorch di dalam dependensi, pendekatan ini mungkin agak terbatas
    Uv memang menyediakan dukungan integrasi yang bagus untuk Pytorch, tetapi hanya dengan header skrip saja, sayangnya tidak ada cara yang jelas untuk memilih wheel index yang paling sesuai (CPU, CUDA, ROCm, dll.)

  • Saya berharap venv yang otomatis dibuat uv bisa lebih mudah dikenali oleh VS Code
    Saat ini Python extension menandai semua import pihak ketiga dengan garis merah
    Solusi sementara saya adalah mencari jalur venv secara manual dari direktori Cache uv lalu mendaftarkannya, tetapi jika venv sering dibuat ulang, saya harus mengulanginya lagi sehingga merepotkan

    • Jalur env bisa ditemukan dengan perintah uv python find --script "${filePath}"
      Saya sedang mengembangkan ekstensi yang akan mendeteksi fitur tersebut secara otomatis di VS Code dan mengaktifkannya

  • Saya sangat menyukai fitur UV ini
    Bahkan jupyter notebook juga bisa dijalankan dengan one-liner seperti berikut tanpa instalasi terpisah

    uv run --with jupyter jupyter notebook

    Semua akan dipasang ke virtual environment sementara, lalu setelahnya dibersihkan
    Jika dijalankan di dalam proyek, dependensi proyek terkait juga akan dikenali secara otomatis

    • Namun sebenarnya pembersihannya tidak sepenuhnya "bersih", karena folder cache uv bisa terus membesar

    • Saya juga sering memakainya seperti uv run --with ipython --with boto3 ipython, dan ini benar-benar sangat menghemat waktu

  • Belakangan saya menemukan isu kecil terkait uv run
    Jika skrip dijalankan dari luar folder proyek, perilakunya adalah mencari pyproject.toml dari current working directory, bukan dari lokasi file skrip yang sebenarnya
    Karena itu, skrip yang dependensinya disimpan di pyproject.toml mungkin tidak akan berjalan semestinya jika dijalankan dari luar dengan bentuk seperti uv run path/to/my/script.py
    Ini bisa diatasi dengan selalu memakai dependensi inline, atau dengan argumen --project, tetapi jadi tidak praktis karena jalur skrip harus ditulis dua kali
    uv sendiri sangat hebat, tetapi karakteristik kecil ini terasa cukup merepotkan

  • Saya sudah cukup puas menggunakan pendekatan shebang khusus uv dan dependensi dalam skrip
    Lebih mengesankan lagi, ada uv lock --script example.py yang bisa membuat file lock khusus untuk satu skrip
    Python packaging sudah berjalan lebih dari 20 tahun, dan mengejutkan rasanya pengalaman yang senatural ini baru muncul sekarang

    • Saya penasaran apa use case untuk membuat lock khusus skrip tunggal
      Di organisasi kami, dependensi dalam lockfile juga dipindai dengan trivy fs uv.lock dan semacamnya untuk mencegah eksekusi kode yang memiliki CVE yang sudah diketahui